Elgato_dark/documenso
1
0
Fork 0
mirror of https://github.com/documenso/documenso synced 2026-04-21 13:27:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

chore: add embed envelope docs (#2576)

Browse source
This commit is contained in:
David Nguyen 2026-03-09 11:50:13 +11:00 committed by GitHub
parent da7b5d12f8
commit 58f0c98038
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 797 additions and 398 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

337
.agents/skills/create-documentation/SKILL.md Normal file
View file

@ -0,0 +1,337 @@
---
name: create-documentation
description: Generate markdown documentation for a module or feature
---
You are creating proper markdown documentation for a feature or guide in the Documenso documentation site.
**Read [WRITING_STYLE.md](../../../WRITING_STYLE.md) first** for tone, formatting conventions, and anti-patterns to avoid.
## Your Task
1. **Identify the scope** - Based on the conversation context, determine what feature or topic needs documentation. Ask the user if unclear.
2. **Identify the audience** - Is this for Users, Developers, or Self-Hosters?
3. **Read the source code** - Understand the feature, API, or configuration being documented.
4. **Read existing docs** - Check `apps/docs/content/docs/` for documentation to update.
5. **Write comprehensive documentation** - Create or update MDX docs following the patterns below.
6. **Update navigation** - Add to the relevant `meta.json` if creating a new page.
## Documentation Framework
This project uses [Fumadocs](https://fumadocs.dev). All documentation lives in `apps/docs/content/docs/` as MDX files. The docs app is a Next.js app at `apps/docs/`.
## Documentation Structure
```
apps/docs/content/docs/
├── index.mdx # Landing page with audience navigation
├── meta.json # Root navigation: guides + resources
├── users/ # Application usage guides
│ ├── meta.json # { "root": true, "pages": [...] }
│ ├── getting-started/ # Account creation, first document
│ ├── documents/ # Upload, recipients, fields, send
│ │ └── advanced/ # AI detection, visibility, placeholders
│ ├── templates/ # Create and use templates
│ ├── organisations/ # Overview, members, groups, SSO, billing
│ │ ├── single-sign-on/
│ │ └── preferences/
│ └── settings/ # Profile, security, API tokens
├── developers/ # API and integration docs
│ ├── meta.json # { "root": true, "pages": [...] }
│ ├── getting-started/ # Authentication, first API call
│ ├── api/ # Documents, recipients, fields, templates, teams
│ ├── webhooks/ # Setup, events, verification
│ ├── embedding/ # Authoring, direct links, CSS vars, SDKs
│ │ └── sdks/ # React, Vue, Svelte, Solid, Preact, Angular
│ ├── examples/ # Common workflows
│ ├── local-development/ # Quickstart, manual, translations
│ └── contributing/ # Contributing translations
├── self-hosting/ # Self-hosting documentation
│ ├── meta.json # { "root": true, "pages": [...] }
│ ├── getting-started/ # Quick start, requirements, tips
│ ├── deployment/ # Docker, docker-compose, Kubernetes, Railway
│ ├── configuration/ # Environment, database, email, storage
│ │ ├── signing-certificate/ # Local, Google Cloud HSM, timestamp
│ │ └── advanced/ # OAuth providers, AI features
│ └── maintenance/ # Upgrades, backups, troubleshooting
├── concepts/ # Shared across audiences
│ └── ... # Document lifecycle, field types, signing
├── compliance/ # eSign, GDPR, standards, certifications
└── policies/ # Terms, privacy, security, licenses
```
### Where to Put Documentation
| Type | Location | When to use |
| ------------------- | ------------------------------------------------ | -------------------------------------------------- |
| **User Guide** | `apps/docs/content/docs/users/<section>/` | UI workflows for using the Documenso web app |
| **Developer Guide** | `apps/docs/content/docs/developers/<section>/` | API reference, SDK guides, webhooks, embedding |
| **Self-Hosting** | `apps/docs/content/docs/self-hosting/<section>/` | Deployment, configuration, environment variables |
| **Concept** | `apps/docs/content/docs/concepts/` | Cross-audience concepts (document lifecycle, etc.) |
| **Compliance** | `apps/docs/content/docs/compliance/` | Legal and regulatory documentation |
### Navigation (meta.json)
Each directory has a `meta.json` controlling navigation order:
```json
{
"title": "Section Title",
"pages": ["getting-started", "documents", "templates"]
}
```
Top-level audience sections use `"root": true`:
```json
{
"title": "Users",
"description": "Send and sign documents",
"root": true,
"pages": ["getting-started", "documents", "templates", "organisations", "settings"]
}
```
Root `meta.json` uses `---Label---` for section dividers:
```json
{
"title": "Documentation",
"pages": [
"---Guides---",
"users",
"developers",
"self-hosting",
"---Resources---",
"concepts",
"compliance",
"policies"
]
}
```
## MDX File Format
### Frontmatter
Every page needs frontmatter:
```yaml
---
title: Upload Documents
description: Upload documents to Documenso to prepare them for signing. Covers supported formats, file size limits, and upload methods.
---
```
### Fumadocs Components
Import components at the top of the file (after frontmatter):
```mdx
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
;
```
Callouts (use sparingly for warnings, beta features, security):
```mdx
<Callout type="info">Informational note about behavior.</Callout>
<Callout type="warn">Warning about potential issues or breaking changes.</Callout>
<Callout type="error">Critical warning about data loss or security.</Callout>
```
Steps (for sequential UI instructions):
```mdx
{/* prettier-ignore */}
<Steps>
<Step>
### Step title
Step description.
</Step>
<Step>
### Next step
Next description.
</Step>
</Steps>
```
Tabs (for multiple approaches or platforms):
````mdx
<Tabs items={['cURL', 'JavaScript', 'Python']}>
<Tab value="cURL">```bash curl -X POST ... ```</Tab>
<Tab value="JavaScript">```typescript const response = await fetch(...) ```</Tab>
</Tabs>
````
## Page Structure by Audience
### User Documentation
```mdx
---
title: Feature Name
description: Brief description for SEO and previews.
---
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
## Limitations
| Limitation | Value |
| ----------------- | -------- |
| Supported format | PDF only |
| Maximum file size | 50MB |
## How to Do the Thing
{/* prettier-ignore */}
<Steps>
<Step>
### Navigate to the page
Open **Settings > Feature**.
</Step>
<Step>
### Configure the setting
Fill in the required fields and click **Save**.
</Step>
</Steps>
---
## See Also
- [Related Guide](/docs/users/related)
```
### Developer Documentation
````mdx
---
title: Documents API
description: Create, manage, and send documents for signing via the API.
---
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
<Callout type="warn">
This guide may not reflect the latest endpoints. For an always up-to-date reference, see the
[OpenAPI Reference](https://openapi.documenso.com).
</Callout>
## Overview
Brief description of the resource and what you can do with it.
## Resource Object
| Property | Type | Description |
| -------- | ------ | ----------------- |
| `id` | string | Unique identifier |
| `status` | string | Current status |
## Create a Resource
```typescript
const response = await fetch('https://app.documenso.com/api/v2/document', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
title: 'Service Agreement',
}),
});
```
````
---
## See Also
- [Related Guide](/docs/developers/related)
````
### Self-Hosting Documentation
```mdx
---
title: Environment Variables
description: Complete reference for all environment variables used to configure Documenso.
---
## Required Variables
| Variable | Description |
| ------------------ | ------------------------------------------------ |
| `NEXTAUTH_SECRET` | Secret key for session encryption (min 32 chars) |
| `DATABASE_URL` | PostgreSQL connection URL |
---
## Optional Variables
| Variable | Default | Description |
| -------------- | ------- | ---------------------- |
| `PORT` | `3000` | Port the server runs on |
---
## See Also
- [Database Configuration](/docs/self-hosting/configuration/database)
````
## Documentation Audiences
Tailor content to the audience:
- **User docs**: Focus on UI workflows, bold UI elements (**Settings**, **Save**), use `>` for navigation paths (**Settings > Team > Members**), number sequential steps, no code required
- **Developer docs**: API/SDK examples, authentication, webhooks, code samples in TypeScript, link to OpenAPI reference
- **Self-hosting docs**: Deployment guides, environment variables, Docker/non-Docker approaches, system requirements, troubleshooting
## Guidelines
See [WRITING_STYLE.md](../../../WRITING_STYLE.md) for complete guidelines. Key points:
- **Tone**: Direct, second-person, no emojis, no excessive personality
- **Examples**: Progressive complexity, all must be valid TypeScript
- **Tables**: Use Sharp-style nested parameter tables for API docs
- **Callouts**: Use sparingly for warnings, beta features, security
- **Cross-references**: Link related docs, add "See Also" sections
- **Navigation**: Update `meta.json` when adding new pages
- **Limitations**: Explicitly list what is NOT supported
- **Images**: Use `.webp` format, store in `apps/docs/public/`
## Process
1. **Identify the audience** - Users, Developers, or Self-Hosters?
2. **Explore the code** - Read source files to understand the feature
3. **Check existing docs** - Look in `apps/docs/content/docs/` for related pages
4. **Draft the structure** - Outline sections before writing
5. **Write content** - Fill in each section following audience-specific patterns
6. **Update navigation** - Add to relevant `meta.json` if creating a new page
7. **Add cross-references** - Link from related docs, add "See Also" section
## Begin
Analyze the conversation context to determine the documentation scope, read the relevant source code, and create comprehensive MDX documentation in `apps/docs/content/docs/`.

0
.opencode/skill/create-justification/SKILL.md → .agents/skills/create-justification/SKILL.md
View file

0
.opencode/skill/create-plan/SKILL.md → .agents/skills/create-plan/SKILL.md
View file

0
.opencode/skill/create-scratch/SKILL.md → .agents/skills/create-scratch/SKILL.md
View file

0
.opencode/skills/envelope-editor-v2-e2e/SKILL.md → .agents/skills/envelope-editor-v2-e2e/SKILL.md
View file

27
.opencode/commands/create-documentation.md Normal file
View file

@ -0,0 +1,27 @@
---
description: Generate markdown documentation for a module or feature
argument-hint: <topic-or-feature>
---
You are generating documentation for the Documenso project.
## Your Task
Load and follow the skill at `.agents/skills/create-documentation/SKILL.md`. It contains the complete instructions for writing documentation including:
- Documentation structure and file locations
- MDX format and Fumadocs components
- Audience-specific patterns (Users, Developers, Self-Hosters)
- Navigation (`meta.json`) updates
- Writing style guidelines
## Context
The topic or feature to document is: `$ARGUMENTS`
## Begin
1. **Read the skill** at `.agents/skills/create-documentation/SKILL.md`
2. **Read WRITING_STYLE.md** for tone and formatting conventions
3. **Follow the skill instructions** to create comprehensive documentation
4. **Use TodoWrite** to track your progress throughout

68
.opencode/commands/create-justification.md
View file

@ -7,69 +7,17 @@ You are creating a new justification file in the `.agents/justifications/` direc
## Your Task ## Your Task
1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended) Load and follow the skill at `.agents/skills/create-justification/SKILL.md`. It contains the complete instructions for creating justification files including:
2. **Gather content** - Collect or generate the justification content
3. **Create the file** - Use the create-justification script to generate the file
## Usage - Unique three-word ID generation
- Frontmatter format with date and title
- Script usage (`scripts/create-justification.ts`)
The script will automatically: ## Context
- Generate a unique three-word ID (e.g., `swift-emerald-river`)
- Create frontmatter with current date and formatted title
- Save the file as `{id}-{slug}.md` in `.agents/justifications/`
## Creating the File The justification slug and optional content: `$ARGUMENTS`
### Option 1: Direct Content
If you have the content ready, run:
```bash
npx tsx scripts/create-justification.ts "$ARGUMENTS" "Your justification content here"
```
### Option 2: Multi-line Content (Heredoc)
For multi-line content, use heredoc:
```bash
npx tsx scripts/create-justification.ts "$ARGUMENTS" << HEREDOC
Your multi-line
justification content
goes here
HEREDOC
```
### Option 3: Pipe Content
You can also pipe content:
```bash
echo "Your content" | npx tsx scripts/create-justification.ts "$ARGUMENTS"
```
## File Format
The created file will have:
```markdown
---
date: 2026-01-13
title: Justification Title
---
Your content here
```
The title is automatically formatted from the slug (e.g., `architecture-decision` → `Architecture Decision`).
## Guidelines
- Use descriptive slugs in kebab-case (e.g., `tech-stack-choice`, `api-design-rationale`)
- Include clear reasoning and context for the decision
- The unique ID ensures no filename conflicts
- Files are automatically dated for organization
## Begin ## Begin
Create a justification file using the slug from `$ARGUMENTS` and appropriate content documenting the reasoning or justification. 1. **Read the skill** at `.agents/skills/create-justification/SKILL.md`
2. **Create the justification file** using the slug from `$ARGUMENTS` and appropriate content documenting the reasoning or justification

69
.opencode/commands/create-plan.md
View file

@ -7,70 +7,17 @@ You are creating a new plan file in the `.agents/plans/` directory.
## Your Task ## Your Task
1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended) Load and follow the skill at `.agents/skills/create-plan/SKILL.md`. It contains the complete instructions for creating plan files including:
2. **Gather content** - Collect or generate the plan content
3. **Create the file** - Use the create-plan script to generate the file
## Usage - Unique three-word ID generation
- Frontmatter format with date and title
- Script usage (`scripts/create-plan.ts`)
The script will automatically: ## Context
- Generate a unique three-word ID (e.g., `happy-blue-moon`) The plan slug and optional content: `$ARGUMENTS`
- Create frontmatter with current date and formatted title
- Save the file as `{id}-{slug}.md` in `.agents/plans/`
## Creating the File
### Option 1: Direct Content
If you have the content ready, run:
```bash
npx tsx scripts/create-plan.ts "$ARGUMENTS" "Your plan content here"
```
### Option 2: Multi-line Content (Heredoc)
For multi-line content, use heredoc:
```bash
npx tsx scripts/create-plan.ts "$ARGUMENTS" << HEREDOC
Your multi-line
plan content
goes here
HEREDOC
```
### Option 3: Pipe Content
You can also pipe content:
```bash
echo "Your content" | npx tsx scripts/create-plan.ts "$ARGUMENTS"
```
## File Format
The created file will have:
```markdown
---
date: 2026-01-13
title: Plan Title
---
Your content here
```
The title is automatically formatted from the slug (e.g., `my-feature` → `My Feature`).
## Guidelines
- Use descriptive slugs in kebab-case (e.g., `user-authentication`, `api-integration`)
- Include clear, actionable plan content
- The unique ID ensures no filename conflicts
- Files are automatically dated for organization
## Begin ## Begin
Create a plan file using the slug from `$ARGUMENTS` and appropriate content for the planning task. 1. **Read the skill** at `.agents/skills/create-plan/SKILL.md`
2. **Create the plan file** using the slug from `$ARGUMENTS` and appropriate content

68
.opencode/commands/create-scratch.md
View file

@ -7,69 +7,17 @@ You are creating a new scratch file in the `.agents/scratches/` directory.
## Your Task ## Your Task
1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended) Load and follow the skill at `.agents/skills/create-scratch/SKILL.md`. It contains the complete instructions for creating scratch files including:
2. **Gather content** - Collect or generate the scratch content
3. **Create the file** - Use the create-scratch script to generate the file
## Usage - Unique three-word ID generation
- Frontmatter format with date and title
- Script usage (`scripts/create-scratch.ts`)
The script will automatically: ## Context
- Generate a unique three-word ID (e.g., `calm-teal-cloud`)
- Create frontmatter with current date and formatted title
- Save the file as `{id}-{slug}.md` in `.agents/scratches/`
## Creating the File The scratch slug and optional content: `$ARGUMENTS`
### Option 1: Direct Content
If you have the content ready, run:
```bash
npx tsx scripts/create-scratch.ts "$ARGUMENTS" "Your scratch content here"
```
### Option 2: Multi-line Content (Heredoc)
For multi-line content, use heredoc:
```bash
npx tsx scripts/create-scratch.ts "$ARGUMENTS" << HEREDOC
Your multi-line
scratch content
goes here
HEREDOC
```
### Option 3: Pipe Content
You can also pipe content:
```bash
echo "Your content" | npx tsx scripts/create-scratch.ts "$ARGUMENTS"
```
## File Format
The created file will have:
```markdown
---
date: 2026-01-13
title: Scratch Title
---
Your content here
```
The title is automatically formatted from the slug (e.g., `quick-notes` → `Quick Notes`).
## Guidelines
- Use descriptive slugs in kebab-case (e.g., `exploration-ideas`, `temporary-notes`)
- Scratch files are for temporary notes, explorations, or ideas
- The unique ID ensures no filename conflicts
- Files are automatically dated for organization
## Begin ## Begin
Create a scratch file using the slug from `$ARGUMENTS` and appropriate content for notes or exploration. 1. **Read the skill** at `.agents/skills/create-scratch/SKILL.md`
2. **Create the scratch file** using the slug from `$ARGUMENTS` and appropriate content for notes or exploration

201
.opencode/commands/document.md
View file

@ -1,201 +0,0 @@
---
description: Generate MDX documentation for a module or feature
argument-hint: <module-path-or-feature>
---
You are creating proper MDX documentation for a module or feature in Documenso using Nextra.
## Your Task
1. **Identify the scope** - What does `$ARGUMENTS` refer to? (file, directory, or feature name)
2. **Read the source code** - Understand the public API, types, and behavior
3. **Read existing docs** - Check if there's documentation to update or reference
4. **Write comprehensive documentation** - Create or update MDX docs in the appropriate location
5. **Update navigation** - Add entry to `_meta.js` if creating a new page
## Documentation Structure
Create documentation in the appropriate location:
- **Developer docs**: `apps/documentation/pages/developers/`
- **User docs**: `apps/documentation/pages/users/`
### File Format
All documentation files must be `.mdx` files with frontmatter:
```mdx
---
title: Page Title
description: Brief description for SEO and meta tags
---
# Page Title
Content starts here...
```
### Navigation
Each directory should have a `_meta.js` file that defines the navigation structure:
```javascript
export default {
index: 'Introduction',
'feature-name': 'Feature Name',
'another-feature': 'Another Feature',
};
```
If creating a new page, add it to the appropriate `_meta.js` file.
### Documentation Format
````mdx
---
title: <Module|Feature Name>
description: Brief description of what this does and when to use it
---
# <Module|Feature Name>
Brief description of what this module/feature does and when to use it.
## Installation
If there are specific packages or imports needed:
```bash
npm install @documenso/package-name
```
## Quick Start
```jsx
// Minimal working example
import { Component } from '@documenso/package';
const Example = () => {
return <Component />;
};
```
## API Reference
### Component/Function Name
Description of what it does.
#### Props/Parameters
| Prop/Param | Type | Description |
| ---------- | -------------------- | ------------------------- |
| prop | `string` | Description of the prop |
| optional | `boolean` (optional) | Optional prop description |
#### Example
```jsx
import { Component } from '@documenso/package';
<Component prop="value" optional={true} />;
```
### Types
#### `TypeName`
```typescript
type TypeName = {
property: string;
optional?: boolean;
};
```
## Examples
### Common Use Case
```jsx
// Full working example
```
### Advanced Usage
```jsx
// More complex example
```
## Related
- [Link to related documentation](/developers/path)
- [Another related page](/users/path)
````
## Guidelines
### Content Quality
- **Be accurate** - Verify behavior by reading the code
- **Be complete** - Document all public API surface
- **Be practical** - Include real, working examples
- **Be concise** - Don't over-explain obvious things
- **Be user-focused** - Write for the target audience (developers or users)
### Code Examples
- Use appropriate language tags: `jsx`, `tsx`, `typescript`, `bash`, `json`
- Show imports when not obvious
- Include expected output in comments where helpful
- Progress from simple to complex
- Use real examples from the codebase when possible
### Formatting
- Always include frontmatter with `title` and `description`
- Use proper markdown headers (h1 for title, h2 for sections)
- Use tables for props/parameters documentation (matching existing style)
- Use code fences with appropriate language tags
- Use Nextra components when appropriate:
- `<Callout type="info">` for notes
- `<Steps>` for step-by-step instructions
- Use relative links for internal documentation (e.g., `/developers/embedding/react`)
### Nextra Components
You can import and use Nextra components:
```jsx
import { Callout, Steps } from 'nextra/components';
<Callout type="info">
This is an informational note.
</Callout>
<Steps>
<Steps.Step>First step</Steps.Step>
<Steps.Step>Second step</Steps.Step>
</Steps>
```
### Maintenance
- Include types inline so docs don't get stale
- Reference source file locations for complex behavior
- Keep examples up-to-date with the codebase
- Update `_meta.js` when adding new pages
## Process
1. **Explore the code** - Read source files to understand the API
2. **Identify the audience** - Is this for developers or users?
3. **Check existing docs** - Look for similar pages to match style
4. **Draft the structure** - Outline sections before writing
5. **Write content** - Fill in each section with frontmatter
6. **Add examples** - Create working code samples
7. **Update navigation** - Add to `_meta.js` if needed
8. **Review** - Read through for clarity and accuracy
## Begin
Analyze `$ARGUMENTS`, read the relevant source code, check existing documentation patterns, and create comprehensive MDX documentation following the Documenso documentation style.

1
.opencode/skills/agent-browser
View file

@ -1 +0,0 @@
../../.agents/skills/agent-browser

56
apps/docs/content/docs/developers/embedding/authoring/index.mdx Normal file
View file

@ -0,0 +1,56 @@
---
title: Authoring
description: Embed document, template, and envelope creation directly in your application.
---
import { Callout } from 'fumadocs-ui/components/callout';
In addition to embedding signing, Documenso supports embedded authoring. It allows your users to create and edit documents, templates, and envelopes without leaving your application.
<Callout type="warn">
Embedded authoring is included with [Enterprise](https://documen.so/enterprise-cta) plans. It is
also available as a paid add-on for the [Platform Plan](https://documen.so/platform-cta-pricing).
Contact sales for access.
</Callout>
## Versions
Embedded authoring is available in two versions:
- **[V1 Authoring](/docs/developers/embedding/authoring/v1)** — Works with V1 Documents and Templates.
- **[V2 Authoring](/docs/developers/embedding/authoring/v2)** — Works with Envelopes, which are the unified model for documents and templates.
### Comparison
| Aspect | V1 | V2 |
| --- | --- | --- |
| Entity model | Documents and Templates (separate) | Envelopes (unified, can be documents or templates) |
| API compatibility | V1 Documents/Templates API | V2 Envelopes API |
| Customization | 6 simple boolean flags | Rich structured settings with sections (general, settings, actions, envelope items, recipients) |
---
## Presign Tokens
Before using any authoring component, obtain a presign token from your backend:
```
POST /api/v2/embedding/create-presign-token
```
This endpoint requires your Documenso API key. The token has a default expiration of 1 hour.
See the [API documentation](https://openapi.documenso.com/reference#tag/embedding) for full details.
<Callout type="warn">
Presign tokens should be created server-side. Never expose your API key in client-side code.
</Callout>
---
## Next Steps
- [V1 Authoring](/docs/developers/embedding/authoring/v1) — Create and edit documents and templates using V1 components
- [V2 Authoring](/docs/developers/embedding/authoring/v2) — Create and edit envelopes using V2 components
- [CSS Variables](/docs/developers/embedding/css-variables) — Customize the appearance of embedded components
- [SDKs](/docs/developers/embedding/sdks) — Framework-specific SDK documentation

4
apps/docs/content/docs/developers/embedding/authoring/meta.json Normal file
View file

@ -0,0 +1,4 @@
{
"title": "Authoring",
"pages": ["v1", "v2"]
}

23
apps/docs/content/docs/developers/embedding/authoring.mdx → apps/docs/content/docs/developers/embedding/authoring/v1.mdx
View file

@ -1,11 +1,11 @@
--- ---
title: Authoring title: V1 Authoring
description: Embed document and template creation directly in your application. description: Embed V1 document and template creation directly in your application.
--- ---
import { Callout } from 'fumadocs-ui/components/callout'; import { Callout } from 'fumadocs-ui/components/callout';
In addition to embedding signing, Documenso supports embedded authoring. It allows your users to create and edit documents and templates without leaving your application. V1 authoring components allow your users to create and edit documents and templates using the V1 Documents and Templates API without leaving your application.
<Callout type="warn"> <Callout type="warn">
Embedded authoring is included with [Enterprise](https://documen.so/enterprise-cta) plans. It is Embedded authoring is included with [Enterprise](https://documen.so/enterprise-cta) plans. It is
@ -15,7 +15,7 @@ In addition to embedding signing, Documenso supports embedded authoring. It allo
## Components ## Components
The SDK provides four authoring components: The SDK provides four V1 authoring components:
| Component | Purpose | | Component | Purpose |
| ----------------------- | ----------------------- | | ----------------------- | ----------------------- |
@ -24,24 +24,16 @@ The SDK provides four authoring components:
| `EmbedUpdateDocumentV1` | Edit existing documents | | `EmbedUpdateDocumentV1` | Edit existing documents |
| `EmbedUpdateTemplateV1` | Edit existing templates | | `EmbedUpdateTemplateV1` | Edit existing templates |
All authoring components require a **presign token** for authentication instead of a regular token.
--- ---
## Presign Tokens ## Presign Tokens
Before using any authoring component, obtain a presign token from your backend: All authoring components require a **presign token** for authentication. See the [Authoring overview](/docs/developers/embedding/authoring) for details on obtaining presign tokens.
```
POST /api/v2/embedding/create-presign-token
```
This endpoint requires your Documenso API key. The token has a default expiration of 1 hour.
See the [API documentation](https://openapi.documenso.com/reference#tag/embedding) for full details.
<Callout type="warn"> <Callout type="warn">
Presign tokens should be created server-side. Never expose your API key in client-side code. A presigned token is NOT an API token
</Callout> </Callout>
--- ---
@ -147,7 +139,7 @@ const TemplateEditor = ({ presignToken, templateId }) => {
| `externalId` | `string` | No | Your reference ID to link with the document or template | | `externalId` | `string` | No | Your reference ID to link with the document or template |
| `host` | `string` | No | Custom host URL. Defaults to `https://app.documenso.com` | | `host` | `string` | No | Custom host URL. Defaults to `https://app.documenso.com` |
| `css` | `string` | No | Custom CSS string (Platform Plan) | | `css` | `string` | No | Custom CSS string (Platform Plan) |
| `cssVars` | `object` | No | CSS variable overrides (Platform Plan) | | `cssVars` | `object` | No | [CSS variable](/docs/developers/embedding/css-variables) overrides (Platform Plan) |
| `darkModeDisabled` | `boolean` | No | Disable dark mode (Platform Plan) | | `darkModeDisabled` | `boolean` | No | Disable dark mode (Platform Plan) |
| `className` | `string` | No | CSS class for the iframe | | `className` | `string` | No | CSS class for the iframe |
| `features` | `object` | No | Feature toggles for the authoring experience | | `features` | `object` | No | Feature toggles for the authoring experience |
@ -301,6 +293,7 @@ Pass extra props to the iframe for testing experimental features:
## See Also ## See Also
- [Embedding Overview](/docs/developers/embedding) - Signing embed concepts and props - [Embedding Overview](/docs/developers/embedding) - Signing embed concepts and props
- [V2 Authoring](/docs/developers/embedding/authoring/v2) - V2 envelope authoring
- [CSS Variables](/docs/developers/embedding/css-variables) - Customize appearance - [CSS Variables](/docs/developers/embedding/css-variables) - Customize appearance
- [Documents API](/docs/developers/api/documents) - Create documents via API - [Documents API](/docs/developers/api/documents) - Create documents via API
- [Templates API](/docs/developers/api/templates) - Create templates via API - [Templates API](/docs/developers/api/templates) - Create templates via API

340
apps/docs/content/docs/developers/embedding/authoring/v2.mdx Normal file
View file

@ -0,0 +1,340 @@
---
title: V2 Authoring
description: Embed envelope creation and editing directly in your application.
---
import { Callout } from 'fumadocs-ui/components/callout';
V2 authoring components allow your users to create and edit envelopes without leaving your application. Envelopes are the unified model for documents and templates in the V2 API.
<Callout type="warn">
Embedded authoring is included with [Enterprise](https://documen.so/enterprise-cta) plans. It is
also available as a paid add-on for the [Platform Plan](https://documen.so/platform-cta-pricing).
Contact sales for access.
</Callout>
## Components
The SDK provides two V2 authoring components:
| Component | Purpose |
| ---------------------- | ------------------------ |
| `EmbedCreateEnvelope` | Create new envelopes |
| `EmbedUpdateEnvelope` | Edit existing envelopes |
---
## Presign Tokens
All authoring components require a **presign token** for authentication. See the [Authoring overview](/docs/developers/embedding/authoring) for details on obtaining presign tokens.
<Callout type="warn">
A presigned token is NOT an API token
</Callout>
---
## Creating Envelopes
Use `EmbedCreateEnvelope` to embed envelope creation. The `type` prop determines whether the envelope is created as a document or template.
```jsx
import { EmbedCreateEnvelope } from '@documenso/embed-react';
const EnvelopeCreator = ({ presignToken }) => {
return (
<div style={{ height: '800px', width: '100%' }}>
<EmbedCreateEnvelope
presignToken={presignToken}
type="DOCUMENT"
externalId="order-12345"
onEnvelopeCreated={(data) => {
console.log('Envelope created:', data.envelopeId);
console.log('External ID:', data.externalId);
}}
/>
</div>
);
};
```
To create a template instead of a document, set `type` to `"TEMPLATE"`:
```jsx
<EmbedCreateEnvelope
presignToken={presignToken}
type="TEMPLATE"
externalId="template-12345"
onEnvelopeCreated={(data) => {
console.log('Template envelope created:', data.envelopeId);
}}
/>
```
---
## Editing Envelopes
Use `EmbedUpdateEnvelope` to embed envelope editing:
```jsx
import { EmbedUpdateEnvelope } from '@documenso/embed-react';
const EnvelopeEditor = ({ presignToken, envelopeId }) => {
return (
<div style={{ height: '800px', width: '100%' }}>
<EmbedUpdateEnvelope
presignToken={presignToken}
envelopeId={envelopeId}
externalId="order-12345"
onEnvelopeUpdated={(data) => {
console.log('Envelope updated:', data.envelopeId);
}}
/>
</div>
);
};
```
---
## Props
### All V2 Authoring Components
| Prop | Type | Required | Description |
| ------------------ | --------- | -------- | -------------------------------------------------------- |
| `presignToken` | `string` | Yes | Authentication token from your backend |
| `externalId` | `string` | No | Your reference ID to link with the envelope |
| `host` | `string` | No | Custom host URL. Defaults to `https://app.documenso.com` |
| `css` | `string` | No | Custom CSS string (Platform Plan) |
| `cssVars` | `object` | No | [CSS variable](/docs/developers/embedding/css-variables) overrides (Platform Plan) |
| `darkModeDisabled` | `boolean` | No | Disable dark mode (Platform Plan) |
| `className` | `string` | No | CSS class for the iframe |
| `features` | `object` | No | Feature toggles for the authoring experience |
### Create Component Only
| Prop | Type | Required | Description |
| ------ | ------------------------------ | -------- | --------------------------------------------------- |
| `type` | `"DOCUMENT"` \| `"TEMPLATE"` | Yes | Whether to create a document or template envelope |
### Update Component Only
| Prop | Type | Required | Description |
| ------------ | -------- | -------- | ---------------------------- |
| `envelopeId` | `string` | Yes | The envelope ID to edit |
---
## Feature Toggles
V2 authoring provides rich, structured feature toggles organized into sections. Pass a partial configuration to customize the authoring experience — any omitted fields will use their defaults.
```jsx
<EmbedCreateEnvelope
presignToken={presignToken}
type="DOCUMENT"
features={{
general: {
allowConfigureEnvelopeTitle: false,
allowUploadAndRecipientStep: false,
allowAddFieldsStep: false,
allowPreviewStep: false,
},
settings: {
allowConfigureSignatureTypes: false,
allowConfigureLanguage: false,
allowConfigureDateFormat: false,
},
recipients: {
allowApproverRole: false,
allowViewerRole: false,
},
}}
/>
```
### General
Controls the overall authoring flow and UI:
| Property | Type | Default | Description |
| ------------------------------- | --------- | ------- | ------------------------------------------------ |
| `allowConfigureEnvelopeTitle` | `boolean` | `true` | Allow editing the envelope title |
| `allowUploadAndRecipientStep` | `boolean` | `true` | Show the upload and recipient configuration step |
| `allowAddFieldsStep` | `boolean` | `true` | Show the add fields step |
| `allowPreviewStep` | `boolean` | `true` | Show the preview step |
| `minimizeLeftSidebar` | `boolean` | `true` | Minimize the left sidebar by default |
### Settings
Controls envelope configuration options. Set to `null` to hide envelope settings entirely.
| Property | Type | Default | Description |
| ----------------------------------- | --------- | ------- | ----------------------------------------- |
| `allowConfigureSignatureTypes` | `boolean` | `true` | Allow configuring signature types |
| `allowConfigureLanguage` | `boolean` | `true` | Allow configuring the language |
| `allowConfigureDateFormat` | `boolean` | `true` | Allow configuring the date format |
| `allowConfigureTimezone` | `boolean` | `true` | Allow configuring the timezone |
| `allowConfigureRedirectUrl` | `boolean` | `true` | Allow configuring a redirect URL |
| `allowConfigureDistribution` | `boolean` | `true` | Allow configuring distribution settings |
| `allowConfigureExpirationPeriod` | `boolean` | `true` | Allow configuring the expiration period |
| `allowConfigureEmailSender` | `boolean` | `true` | Allow configuring the email sender |
| `allowConfigureEmailReplyTo` | `boolean` | `true` | Allow configuring the email reply-to |
### Actions
Controls available actions during authoring:
| Property | Type | Default | Description |
| ------------------ | --------- | ------- | ------------------------ |
| `allowAttachments` | `boolean` | `true` | Allow adding attachments |
### Envelope Items
Controls how envelope items (individual files within the envelope) can be managed. Set to `null` to prevent any item modifications.
| Property | Type | Default | Description |
| --------------------- | --------- | ------- | ------------------------------------ |
| `allowConfigureTitle` | `boolean` | `true` | Allow editing item titles |
| `allowConfigureOrder` | `boolean` | `true` | Allow reordering items |
| `allowUpload` | `boolean` | `true` | Allow uploading new items |
| `allowDelete` | `boolean` | `true` | Allow deleting items |
### Recipients
Controls recipient configuration options. Set to `null` to prevent any recipient modifications.
| Property | Type | Default | Description |
| --------------------------------- | --------- | ------- | ---------------------------------------- |
| `allowConfigureSigningOrder` | `boolean` | `true` | Allow configuring the signing order |
| `allowConfigureDictateNextSigner` | `boolean` | `true` | Allow configuring dictate next signer |
| `allowApproverRole` | `boolean` | `true` | Allow the approver recipient role |
| `allowViewerRole` | `boolean` | `true` | Allow the viewer recipient role |
| `allowCCerRole` | `boolean` | `true` | Allow the CC recipient role |
| `allowAssistantRole` | `boolean` | `true` | Allow the assistant recipient role |
### Disabling Steps
You can also disable entire steps of the authoring flow. This allows you to skip steps that are not relevant to your use case:
```jsx
<EmbedCreateEnvelope
presignToken={presignToken}
type="DOCUMENT"
features={{
general: {
allowUploadAndRecipientStep: false, // Skip the upload and recipient step
allowAddFieldsStep: false, // Skip the add fields step
allowPreviewStep: false, // Skip the preview step
},
settings: null, // Hide all envelope settings
envelopeItems: null, // Prevent item modifications
recipients: null, // Prevent recipient modifications
}}
/>
```
---
## Event Callbacks
### `onEnvelopeCreated`
Fired when an envelope is successfully created:
| Field | Type | Description |
| ------------ | ---------------- | --------------------------------------- |
| `envelopeId` | `string` | The ID of the created envelope |
| `externalId` | `string \| null` | Your external reference ID, if provided |
### `onEnvelopeUpdated`
Fired when an envelope is successfully updated:
| Field | Type | Description |
| ------------ | ---------------- | --------------------------------------- |
| `envelopeId` | `string` | The ID of the updated envelope |
| `externalId` | `string \| null` | Your external reference ID, if provided |
---
## Complete Integration Example
This example shows a full workflow where users create an envelope and then edit it:
```tsx
import { useState } from 'react';
import { EmbedCreateEnvelope, EmbedUpdateEnvelope } from '@documenso/embed-react';
const EnvelopeManager = ({ presignToken }) => {
const [envelopeId, setEnvelopeId] = useState(null);
const [mode, setMode] = useState('create');
if (mode === 'success') {
return (
<div>
<h2>Envelope updated successfully</h2>
<button
onClick={() => {
setEnvelopeId(null);
setMode('create');
}}
>
Create Another Envelope
</button>
</div>
);
}
if (mode === 'edit' && envelopeId) {
return (
<div style={{ height: '800px', width: '100%' }}>
<button onClick={() => setMode('create')}>Back to Create</button>
<EmbedUpdateEnvelope
presignToken={presignToken}
envelopeId={envelopeId}
onEnvelopeUpdated={(data) => {
console.log('Envelope updated:', data.envelopeId);
setMode('success');
}}
/>
</div>
);
}
return (
<div style={{ height: '800px', width: '100%' }}>
<EmbedCreateEnvelope
presignToken={presignToken}
type="DOCUMENT"
features={{
general: {
allowConfigureEnvelopeTitle: false,
},
settings: {
allowConfigureSignatureTypes: false,
allowConfigureLanguage: false,
},
}}
onEnvelopeCreated={(data) => {
console.log('Envelope created:', data.envelopeId);
setEnvelopeId(data.envelopeId);
setMode('edit');
}}
/>
</div>
);
};
```
---
## See Also
- [Authoring Overview](/docs/developers/embedding/authoring) - V1 vs V2 comparison and presign tokens
- [V1 Authoring](/docs/developers/embedding/authoring/v1) - V1 document and template authoring
- [Embedding Overview](/docs/developers/embedding) - Signing embed concepts and props
- [CSS Variables](/docs/developers/embedding/css-variables) - Customize appearance

1
apps/docs/content/docs/developers/embedding/css-variables.mdx
View file

@ -59,6 +59,7 @@ Use the `cssVars` prop on any embed component to override default colors, spacin
| `destructiveForeground` | Destructive/danger text color | | `destructiveForeground` | Destructive/danger text color |
| `ring` | Focus ring color | | `ring` | Focus ring color |
| `warning` | Warning/alert color | | `warning` | Warning/alert color |
| `envelopeEditorBackground` | Envelope editor background color. _V2 Envelope Editor only._ |
### Spacing ### Spacing