letsbe/pn-new-crm
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

fix(integration): webhook v2 events, storage migrate, test theatre

Browse Source 
- F1: DOCUMENT_DECLINED handler (v2 Decline vs Reject) — routes to same
  handler as DOCUMENT_REJECTED until product refines downstream UX
- Add RECIPIENT_VIEWED / RECIPIENT_SIGNED v2-alias cases with telemetry
  logging so we see when v2 deployments emit them
- D1: populate TABLES_WITH_STORAGE_KEYS (files, berth_pdf_versions,
  brochure_versions, gdpr_exports) — was an empty list, migrated 0 files
- MinIO putObject/getObject/statObject/removeObject socket timeout wrapper
  to prevent worker hangs on TCP blackhole (30s deadline)
- E1: convert test.skip on smoke-setup infra failure to throw new Error
  so green-skipped silence becomes a real test failure (Playwright
  doesn't expose vitest's expect.fail)
- Regression tests: folderId='' → null transform, applyEntityRestoredSuffix
  no-op (never-archived), syncEntityFolderName collision loop past (2)

Note: matching .env.example documentation (D2 — bare DOCUMENSO_API_URL,
DOCUMENSO_API_VERSION, MINIO_AUTO_CREATE_BUCKET, DOCUMENSO_TEMPLATE_ID_EOI,
recipient role id vars) prepared but not committed — pre-commit hook
blocks .env*. Apply manually via the separate .env workflow.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt
2026-05-11 14:02:26 +02:00
parent 955911302b
commit 9a5ba87d6c
7 changed files with 352 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
src/app/api/webhooks/documenso/route.ts
View File

@@ -145,9 +145,19 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
try {
switch (event) {
case 'DOCUMENT_SIGNED':
case 'DOCUMENT_RECIPIENT_COMPLETED': {
case 'DOCUMENT_RECIPIENT_COMPLETED':
case 'RECIPIENT_SIGNED': {
// v1.13 fires DOCUMENT_SIGNED per recipient sign;
// 2.x fires DOCUMENT_RECIPIENT_COMPLETED for the same semantics.
// Some 2.x deployments emit RECIPIENT_SIGNED as a v2-flavoured alias —
// log when we see it (telemetry) and route to the same handler so v2
// deployments don't silently drop per-recipient signs.
if (event === 'RECIPIENT_SIGNED') {
logger.info(
{ event, documensoId },
'Documenso v2 RECIPIENT_SIGNED received — routing to recipient-signed handler',
);
}
const signedRecipients = recipients.filter(
(r) => r.signingStatus === 'SIGNED' || Boolean(r.signedAt),
);
@@ -162,13 +172,23 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
break;
}
case 'DOCUMENT_OPENED': {
case 'DOCUMENT_OPENED':
case 'RECIPIENT_VIEWED': {
// Documenso v1 sends `readStatus: 'OPENED'`; v2 has used both
// upper and lower case across releases and may omit the field
// entirely (the event itself signals the open). Treat the event
// as the signal: dispatch a per-recipient open for every
// recipient on the document so v2 deployments stop silently
// dropping opens.
//
// RECIPIENT_VIEWED is the v2-flavoured alias for the same semantics
// — log when we see it (telemetry) and route to the same handler.
if (event === 'RECIPIENT_VIEWED') {
logger.info(
{ event, documensoId },
'Documenso v2 RECIPIENT_VIEWED received — routing to document-opened handler',
);
}
const openedRecipients = recipients.filter(
(r) => !r.readStatus || String(r.readStatus).toUpperCase() === 'OPENED',
);
@@ -187,8 +207,17 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
await handleDocumentCompleted({ documentId: documensoId, ...portScope });
break;
case 'DOCUMENT_REJECTED': {
const rejecting = recipients.find((r) => r.signingStatus === 'REJECTED');
case 'DOCUMENT_REJECTED':
case 'DOCUMENT_DECLINED': {
// Documenso v2 distinguishes Decline (recipient refuses to sign) from
// Reject (admin cancels). Both currently map to the same "rejected"
// terminal state in our domain — `handleDocumentRejected` records who
// refused and freezes the workflow. Product may later refine
// downstream UX (different audit tags / notifications), but the
// storage shape is identical for now so they share a handler.
const rejecting = recipients.find(
(r) => r.signingStatus === 'REJECTED' || r.signingStatus === 'DECLINED',
);
await handleDocumentRejected({
documentId: documensoId,
recipientEmail: rejecting?.email,

29
src/lib/storage/migrate.ts
View File

@@ -32,14 +32,31 @@ export interface StorageKeyTable {
}
/**
* Phase 6a ships an empty list — `berth_pdf_versions` and `brochure_versions`
* land in Phase 6b. Add new entries here when new file-bearing tables are
* introduced. The migration script reads each named table via raw SQL so it
* does not need to import every domain's Drizzle schema.
* Tables that hold blob references the migration script must walk.
*
* Column naming is intentionally inconsistent across the schema for historical
* reasons:
* - `files.storage_path` (oldest table, named before §4.7a rename)
* - `berth_pdf_versions.storage_key` (Phase 6b — followed the new convention)
* - `brochure_versions.storage_key` (Phase 6b)
* - `gdpr_exports.storage_key` (worker-uploaded export bundle)
*
* None of these tables carry a per-row content-type column today
* (`files.mime_type` exists but isn't the same semantics — it's the
* original-upload mime, not the stored object's Content-Type header). The
* migration falls back to `application/octet-stream` when
* `contentTypeColumn` is omitted; the byte stream is what matters for the
* sha256-verified round-trip and the original Content-Type is already
* persisted on the source object's S3 metadata.
*
* The `report_snapshots` table called out in the audit does not exist yet.
* Add it here when it lands.
*/
export const TABLES_WITH_STORAGE_KEYS: StorageKeyTable[] = [
// { table: 'berth_pdf_versions', keyColumn: 'storage_key', pkColumn: 'id', contentTypeColumn: 'content_type' },
// { table: 'brochure_versions', keyColumn: 'storage_key', pkColumn: 'id', contentTypeColumn: 'content_type' },
{ table: 'files', keyColumn: 'storage_path', pkColumn: 'id' },
{ table: 'berth_pdf_versions', keyColumn: 'storage_key', pkColumn: 'id' },
{ table: 'brochure_versions', keyColumn: 'storage_key', pkColumn: 'id' },
{ table: 'gdpr_exports', keyColumn: 'storage_key', pkColumn: 'id' },
];
const ADVISORY_LOCK_KEY = 0xc7000a01;

88
src/lib/storage/s3.ts
View File

@@ -30,6 +30,32 @@ interface S3BackendConfig {
forcePathStyle?: boolean;
}
/**
* Socket timeout wrapper. The `minio` JS client does not propagate
* `fetchWithTimeout` semantics into `putObject` / `getObject` / `statObject`
* (its underlying `node:http(s)` agent has no default request-timeout), so a
* TCP-blackhole between the worker and the storage host can stall a job
* indefinitely. We race every call against a deadline and fail loud — the
* caller's retry/error path is far better than a stuck queue worker.
*
* The MinIO client doesn't accept an AbortSignal on these methods, so the
* underlying request keeps running in the background after timeout. That's
* acceptable here: the alternative is keeping the worker hung forever; the
* underlying socket is closed by Node's keep-alive timeouts on the next
* idle cycle.
*/
const STORAGE_DEFAULT_TIMEOUT_MS = 30_000;
function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
let timer: NodeJS.Timeout | null = null;
const timeout = new Promise<T>((_, reject) => {
timer = setTimeout(() => reject(new Error(`S3 ${label} timed out after ${ms}ms`)), ms);
});
return Promise.race([promise, timeout]).finally(() => {
if (timer) clearTimeout(timer);
});
}
interface ResolvedConfig {
endpoint: string;
port: number;
@@ -114,10 +140,18 @@ export class S3Backend implements StorageBackend {
// is missing — we'll create it. Otherwise we throw so the boot fails
// fast and the deployment-time misconfig is loud.
try {
const exists = await client.bucketExists(resolved.bucket);
const exists = await withTimeout(
client.bucketExists(resolved.bucket),
STORAGE_DEFAULT_TIMEOUT_MS,
'bucketExists',
);
if (!exists) {
if (process.env.MINIO_AUTO_CREATE_BUCKET === 'true') {
await client.makeBucket(resolved.bucket, resolved.region);
await withTimeout(
client.makeBucket(resolved.bucket, resolved.region),
STORAGE_DEFAULT_TIMEOUT_MS,
'makeBucket',
);
logger.info(
{ bucket: resolved.bucket, endpoint: resolved.endpoint },
'S3 bucket auto-created (MINIO_AUTO_CREATE_BUCKET=true)',
@@ -153,16 +187,24 @@ export class S3Backend implements StorageBackend {
const buffer = Buffer.isBuffer(body) ? body : await streamToBuffer(body);
const sha256 = opts.sha256 ?? createHash('sha256').update(buffer).digest('hex');
await this.client.putObject(this.bucket, key, buffer, buffer.length, {
'Content-Type': opts.contentType,
});
await withTimeout(
this.client.putObject(this.bucket, key, buffer, buffer.length, {
'Content-Type': opts.contentType,
}),
STORAGE_DEFAULT_TIMEOUT_MS,
`putObject(${key})`,
);
return { key, sizeBytes: buffer.length, sha256 };
}
async get(key: string): Promise<NodeJS.ReadableStream> {
try {
return await this.client.getObject(this.bucket, key);
return await withTimeout(
this.client.getObject(this.bucket, key),
STORAGE_DEFAULT_TIMEOUT_MS,
`getObject(${key})`,
);
} catch (err) {
const code = (err as { code?: string } | null)?.code;
if (code === 'NoSuchKey' || code === 'NotFound') {
@@ -174,7 +216,11 @@ export class S3Backend implements StorageBackend {
async head(key: string): Promise<{ sizeBytes: number; contentType: string } | null> {
try {
const stat = await this.client.statObject(this.bucket, key);
const stat = await withTimeout(
this.client.statObject(this.bucket, key),
STORAGE_DEFAULT_TIMEOUT_MS,
`statObject(${key})`,
);
const meta = (stat.metaData ?? {}) as Record<string, string>;
const contentType =
meta['content-type'] ?? meta['Content-Type'] ?? 'application/octet-stream';
@@ -188,7 +234,11 @@ export class S3Backend implements StorageBackend {
async delete(key: string): Promise<void> {
try {
await this.client.removeObject(this.bucket, key);
await withTimeout(
this.client.removeObject(this.bucket, key),
STORAGE_DEFAULT_TIMEOUT_MS,
`removeObject(${key})`,
);
} catch (err) {
const code = (err as { code?: string } | null)?.code;
if (code === 'NotFound' || code === 'NoSuchKey') return;
@@ -232,14 +282,26 @@ export class S3Backend implements StorageBackend {
const sentinelKey = `_health/${Date.now()}.txt`;
const payload = Buffer.from('ok', 'utf8');
try {
await this.client.putObject(this.bucket, sentinelKey, payload, payload.length, {
'Content-Type': 'text/plain',
});
const stat = await this.client.statObject(this.bucket, sentinelKey);
await withTimeout(
this.client.putObject(this.bucket, sentinelKey, payload, payload.length, {
'Content-Type': 'text/plain',
}),
STORAGE_DEFAULT_TIMEOUT_MS,
`healthCheck:put(${sentinelKey})`,
);
const stat = await withTimeout(
this.client.statObject(this.bucket, sentinelKey),
STORAGE_DEFAULT_TIMEOUT_MS,
`healthCheck:stat(${sentinelKey})`,
);
if (stat.size !== payload.length) {
return { ok: false, error: 'sentinel size mismatch' };
}
await this.client.removeObject(this.bucket, sentinelKey);
await withTimeout(
this.client.removeObject(this.bucket, sentinelKey),
STORAGE_DEFAULT_TIMEOUT_MS,
`healthCheck:remove(${sentinelKey})`,
);
return { ok: true };
} catch (err) {
return { ok: false, error: (err as Error).message };