From 58f0c98038fd22ed550e8bbf9a51b4dcd5666721 Mon Sep 17 00:00:00 2001 From: David Nguyen Date: Mon, 9 Mar 2026 11:50:13 +1100 Subject: [PATCH] chore: add embed envelope docs (#2576) --- .agents/skills/create-documentation/SKILL.md | 337 +++++++++++++++++ .../skills}/create-justification/SKILL.md | 0 .../skills}/create-plan/SKILL.md | 0 .../skills}/create-scratch/SKILL.md | 0 .../skills/envelope-editor-v2-e2e/SKILL.md | 0 .opencode/commands/create-documentation.md | 27 ++ .opencode/commands/create-justification.md | 68 +--- .opencode/commands/create-plan.md | 69 +--- .opencode/commands/create-scratch.md | 68 +--- .opencode/commands/document.md | 201 ----------- .opencode/skills/agent-browser | 1 - .../developers/embedding/authoring/index.mdx | 56 +++ .../developers/embedding/authoring/meta.json | 4 + .../{authoring.mdx => authoring/v1.mdx} | 23 +- .../developers/embedding/authoring/v2.mdx | 340 ++++++++++++++++++ .../developers/embedding/css-variables.mdx | 1 + 16 files changed, 797 insertions(+), 398 deletions(-) create mode 100644 .agents/skills/create-documentation/SKILL.md rename {.opencode/skill => .agents/skills}/create-justification/SKILL.md (100%) rename {.opencode/skill => .agents/skills}/create-plan/SKILL.md (100%) rename {.opencode/skill => .agents/skills}/create-scratch/SKILL.md (100%) rename {.opencode => .agents}/skills/envelope-editor-v2-e2e/SKILL.md (100%) create mode 100644 .opencode/commands/create-documentation.md delete mode 100644 .opencode/commands/document.md delete mode 120000 .opencode/skills/agent-browser create mode 100644 apps/docs/content/docs/developers/embedding/authoring/index.mdx create mode 100644 apps/docs/content/docs/developers/embedding/authoring/meta.json rename apps/docs/content/docs/developers/embedding/{authoring.mdx => authoring/v1.mdx} (89%) create mode 100644 apps/docs/content/docs/developers/embedding/authoring/v2.mdx diff --git a/.agents/skills/create-documentation/SKILL.md b/.agents/skills/create-documentation/SKILL.md new file mode 100644 index 000000000..0524ae691 --- /dev/null +++ b/.agents/skills/create-documentation/SKILL.md @@ -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/
/` | UI workflows for using the Documenso web app | +| **Developer Guide** | `apps/docs/content/docs/developers/
/` | API reference, SDK guides, webhooks, embedding | +| **Self-Hosting** | `apps/docs/content/docs/self-hosting/
/` | 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 +Informational note about behavior. + +Warning about potential issues or breaking changes. + +Critical warning about data loss or security. +``` + +Steps (for sequential UI instructions): + +```mdx +{/* prettier-ignore */} + + + ### Step title + + Step description. + + + + ### Next step + + Next description. + + + +``` + +Tabs (for multiple approaches or platforms): + +````mdx + + ```bash curl -X POST ... ``` + ```typescript const response = await fetch(...) ``` + +```` + +## 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 */} + + + ### Navigate to the page + + Open **Settings > Feature**. + + + + ### Configure the setting + + Fill in the required fields and click **Save**. + + + + +--- + +## 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'; + + + This guide may not reflect the latest endpoints. For an always up-to-date reference, see the + [OpenAPI Reference](https://openapi.documenso.com). + + +## 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/`. diff --git a/.opencode/skill/create-justification/SKILL.md b/.agents/skills/create-justification/SKILL.md similarity index 100% rename from .opencode/skill/create-justification/SKILL.md rename to .agents/skills/create-justification/SKILL.md diff --git a/.opencode/skill/create-plan/SKILL.md b/.agents/skills/create-plan/SKILL.md similarity index 100% rename from .opencode/skill/create-plan/SKILL.md rename to .agents/skills/create-plan/SKILL.md diff --git a/.opencode/skill/create-scratch/SKILL.md b/.agents/skills/create-scratch/SKILL.md similarity index 100% rename from .opencode/skill/create-scratch/SKILL.md rename to .agents/skills/create-scratch/SKILL.md diff --git a/.opencode/skills/envelope-editor-v2-e2e/SKILL.md b/.agents/skills/envelope-editor-v2-e2e/SKILL.md similarity index 100% rename from .opencode/skills/envelope-editor-v2-e2e/SKILL.md rename to .agents/skills/envelope-editor-v2-e2e/SKILL.md diff --git a/.opencode/commands/create-documentation.md b/.opencode/commands/create-documentation.md new file mode 100644 index 000000000..03fa54bf3 --- /dev/null +++ b/.opencode/commands/create-documentation.md @@ -0,0 +1,27 @@ +--- +description: Generate markdown documentation for a module or feature +argument-hint: +--- + +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 diff --git a/.opencode/commands/create-justification.md b/.opencode/commands/create-justification.md index f36a04f15..72f10d23b 100644 --- a/.opencode/commands/create-justification.md +++ b/.opencode/commands/create-justification.md @@ -7,69 +7,17 @@ You are creating a new justification file in the `.agents/justifications/` direc ## Your Task -1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended) -2. **Gather content** - Collect or generate the justification content -3. **Create the file** - Use the create-justification script to generate the file +Load and follow the skill at `.agents/skills/create-justification/SKILL.md`. It contains the complete instructions for creating justification files including: -## Usage +- Unique three-word ID generation +- Frontmatter format with date and title +- Script usage (`scripts/create-justification.ts`) -The script will automatically: -- 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/` +## Context -## Creating the File - -### 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 +The justification slug and optional content: `$ARGUMENTS` ## 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 diff --git a/.opencode/commands/create-plan.md b/.opencode/commands/create-plan.md index cde144440..215ab83a2 100644 --- a/.opencode/commands/create-plan.md +++ b/.opencode/commands/create-plan.md @@ -7,70 +7,17 @@ You are creating a new plan file in the `.agents/plans/` directory. ## Your Task -1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended) -2. **Gather content** - Collect or generate the plan content -3. **Create the file** - Use the create-plan script to generate the file +Load and follow the skill at `.agents/skills/create-plan/SKILL.md`. It contains the complete instructions for creating plan files including: -## 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`) -- 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 +The plan slug and optional content: `$ARGUMENTS` ## 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 diff --git a/.opencode/commands/create-scratch.md b/.opencode/commands/create-scratch.md index 1f4138944..abf06d340 100644 --- a/.opencode/commands/create-scratch.md +++ b/.opencode/commands/create-scratch.md @@ -7,69 +7,17 @@ You are creating a new scratch file in the `.agents/scratches/` directory. ## Your Task -1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended) -2. **Gather content** - Collect or generate the scratch content -3. **Create the file** - Use the create-scratch script to generate the file +Load and follow the skill at `.agents/skills/create-scratch/SKILL.md`. It contains the complete instructions for creating scratch files including: -## Usage +- Unique three-word ID generation +- Frontmatter format with date and title +- Script usage (`scripts/create-scratch.ts`) -The script will automatically: -- 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/` +## Context -## Creating the File - -### 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 +The scratch slug and optional content: `$ARGUMENTS` ## 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 diff --git a/.opencode/commands/document.md b/.opencode/commands/document.md deleted file mode 100644 index 72ca40259..000000000 --- a/.opencode/commands/document.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -description: Generate MDX documentation for a module or feature -argument-hint: ---- - -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: -description: Brief description of what this does and when to use it ---- - -# - -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 ; -}; -``` - -## 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'; - -; -``` - -### 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: - - `` for notes - - `` 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'; - - - This is an informational note. - - - - First step - Second step - -``` - -### 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. diff --git a/.opencode/skills/agent-browser b/.opencode/skills/agent-browser deleted file mode 120000 index e298b7be3..000000000 --- a/.opencode/skills/agent-browser +++ /dev/null @@ -1 +0,0 @@ -../../.agents/skills/agent-browser \ No newline at end of file diff --git a/apps/docs/content/docs/developers/embedding/authoring/index.mdx b/apps/docs/content/docs/developers/embedding/authoring/index.mdx new file mode 100644 index 000000000..834d3cc71 --- /dev/null +++ b/apps/docs/content/docs/developers/embedding/authoring/index.mdx @@ -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. + + + 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. + + +## 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. + + + Presign tokens should be created server-side. Never expose your API key in client-side code. + + +--- + +## 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 diff --git a/apps/docs/content/docs/developers/embedding/authoring/meta.json b/apps/docs/content/docs/developers/embedding/authoring/meta.json new file mode 100644 index 000000000..45cb7a47b --- /dev/null +++ b/apps/docs/content/docs/developers/embedding/authoring/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Authoring", + "pages": ["v1", "v2"] +} diff --git a/apps/docs/content/docs/developers/embedding/authoring.mdx b/apps/docs/content/docs/developers/embedding/authoring/v1.mdx similarity index 89% rename from apps/docs/content/docs/developers/embedding/authoring.mdx rename to apps/docs/content/docs/developers/embedding/authoring/v1.mdx index 030f9ae93..9d33e57e9 100644 --- a/apps/docs/content/docs/developers/embedding/authoring.mdx +++ b/apps/docs/content/docs/developers/embedding/authoring/v1.mdx @@ -1,11 +1,11 @@ --- -title: Authoring -description: Embed document and template creation directly in your application. +title: V1 Authoring +description: Embed V1 document and template 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 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. 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 -The SDK provides four authoring components: +The SDK provides four V1 authoring components: | Component | Purpose | | ----------------------- | ----------------------- | @@ -24,24 +24,16 @@ The SDK provides four authoring components: | `EmbedUpdateDocumentV1` | Edit existing documents | | `EmbedUpdateTemplateV1` | Edit existing templates | -All authoring components require a **presign token** for authentication instead of a regular token. --- ## 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. - Presign tokens should be created server-side. Never expose your API key in client-side code. + A presigned token is NOT an API token --- @@ -147,7 +139,7 @@ const TemplateEditor = ({ presignToken, templateId }) => { | `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` | | `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) | | `className` | `string` | No | CSS class for the iframe | | `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 - [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 - [Documents API](/docs/developers/api/documents) - Create documents via API - [Templates API](/docs/developers/api/templates) - Create templates via API diff --git a/apps/docs/content/docs/developers/embedding/authoring/v2.mdx b/apps/docs/content/docs/developers/embedding/authoring/v2.mdx new file mode 100644 index 000000000..deaabd542 --- /dev/null +++ b/apps/docs/content/docs/developers/embedding/authoring/v2.mdx @@ -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. + + + 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. + + +## 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. + + + A presigned token is NOT an API token + + +--- + +## 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 ( +
+ { + console.log('Envelope created:', data.envelopeId); + console.log('External ID:', data.externalId); + }} + /> +
+ ); +}; +``` + +To create a template instead of a document, set `type` to `"TEMPLATE"`: + +```jsx + { + 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 ( +
+ { + console.log('Envelope updated:', data.envelopeId); + }} + /> +
+ ); +}; +``` + +--- + +## 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 + +``` + +### 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 + +``` + +--- + +## 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 ( +
+

Envelope updated successfully

+ +
+ ); + } + + if (mode === 'edit' && envelopeId) { + return ( +
+ + { + console.log('Envelope updated:', data.envelopeId); + setMode('success'); + }} + /> +
+ ); + } + + return ( +
+ { + console.log('Envelope created:', data.envelopeId); + setEnvelopeId(data.envelopeId); + setMode('edit'); + }} + /> +
+ ); +}; +``` + +--- + +## 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 diff --git a/apps/docs/content/docs/developers/embedding/css-variables.mdx b/apps/docs/content/docs/developers/embedding/css-variables.mdx index e95b0fda4..ae7185964 100644 --- a/apps/docs/content/docs/developers/embedding/css-variables.mdx +++ b/apps/docs/content/docs/developers/embedding/css-variables.mdx @@ -59,6 +59,7 @@ Use the `cssVars` prop on any embed component to override default colors, spacin | `destructiveForeground` | Destructive/danger text color | | `ring` | Focus ring color | | `warning` | Warning/alert color | +| `envelopeEditorBackground` | Envelope editor background color. _V2 Envelope Editor only._ | ### Spacing