@cosmicdrift/kumiko-samples 0.415.0 → 0.417.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/packages/bundled-features/package.json +21 -1
- package/packages/bundled-features/src/agent-tools/changes.json +6 -0
- package/packages/bundled-features/src/agent-tools/tool-catalog.ts +20 -1
- package/packages/bundled-features/src/agent-tools/tool-dispatch.ts +19 -5
- package/packages/bundled-features/src/channel-whatsapp/changes.json +6 -0
- package/packages/bundled-features/src/channel-whatsapp/constants.ts +1 -0
- package/packages/bundled-features/src/channel-whatsapp/graph-client.ts +37 -1
- package/packages/bundled-features/src/handbook-knowledge/README.md +64 -0
- package/packages/bundled-features/src/handbook-knowledge/changes.json +8 -0
- package/packages/bundled-features/src/handbook-knowledge/constants.ts +8 -0
- package/packages/bundled-features/src/handbook-knowledge/feature.ts +34 -0
- package/packages/bundled-features/src/handbook-knowledge/handbook-index.ts +66 -0
- package/packages/bundled-features/src/handbook-knowledge/handlers.ts +77 -0
- package/packages/bundled-features/src/handbook-knowledge/index.ts +10 -0
- package/packages/bundled-features/src/helpdesk/screens.ts +5 -1
- package/packages/bundled-features/src/signature/README.md +66 -0
- package/packages/bundled-features/src/signature/changes.json +22 -0
- package/packages/bundled-features/src/signature/entity.ts +192 -0
- package/packages/bundled-features/src/signature/feature.ts +125 -0
- package/packages/bundled-features/src/signature/files.ts +107 -0
- package/packages/bundled-features/src/signature/grant.ts +79 -0
- package/packages/bundled-features/src/signature/handlers/anonymous.write.ts +88 -0
- package/packages/bundled-features/src/signature/handlers/cancel.write.ts +48 -0
- package/packages/bundled-features/src/signature/handlers/issue-link.write.ts +77 -0
- package/packages/bundled-features/src/signature/handlers/lifecycle.write.ts +99 -0
- package/packages/bundled-features/src/signature/handlers/link-internal.write.ts +261 -0
- package/packages/bundled-features/src/signature/handlers/request.write.ts +120 -0
- package/packages/bundled-features/src/signature/handlers/revoke-link.write.ts +37 -0
- package/packages/bundled-features/src/signature/handlers/sign-in-person.write.ts +73 -0
- package/packages/bundled-features/src/signature/i18n.ts +52 -0
- package/packages/bundled-features/src/signature/index.ts +35 -0
- package/packages/bundled-features/src/signature/lib.ts +125 -0
- package/packages/bundled-features/src/signature/options.ts +64 -0
- package/packages/bundled-features/src/signature/payloads.ts +71 -0
- package/packages/bundled-features/src/signature/png.ts +169 -0
- package/packages/bundled-features/src/signature/screens.ts +117 -0
- package/packages/bundled-features/src/signature/signature-page.ts +93 -0
- package/packages/bundled-features/src/signature/signing.ts +77 -0
- package/packages/bundled-features/src/signature/static-sign.ts +99 -0
- package/packages/bundled-features/src/signature/subject-queries.ts +144 -0
- package/packages/bundled-features/src/signature/subject-scope.ts +43 -0
- package/packages/bundled-features/src/signature/sweep.ts +161 -0
- package/packages/bundled-features/src/signature/user-data.ts +159 -0
- package/packages/bundled-features/src/signature/web/constants.ts +92 -0
- package/packages/bundled-features/src/signature/web/index.ts +31 -0
- package/packages/bundled-features/src/signature/web/pad.ts +147 -0
- package/packages/bundled-features/src/signature/web/signature-pad.tsx +82 -0
- package/packages/bundled-features/src/subscription-stripe/changes.json +6 -0
- package/packages/bundled-features/src/subscription-stripe/feature.ts +9 -0
- package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts +7 -1
- package/samples/apps/use-all-bundled/feature-manifest.json +63 -1
- package/samples/apps/use-all-bundled/kumiko/migrations/0068_signature.rebuild.json +4 -0
- package/samples/apps/use-all-bundled/src/run-config.ts +35 -1
- package/samples/recipes/dashboard-stats/README.md +4 -0
- package/samples/recipes/dashboard-stats/src/feature.ts +47 -0
- package/samples/recipes/embedded/README.md +4 -0
- package/samples/recipes/embedded/src/entities/invoice.ts +6 -0
- package/samples/recipes/embedded/src/feature.ts +7 -1
- package/samples/recipes/embedded/src/handlers/invoice-receive.write.ts +1 -0
- package/samples/recipes/embedded/src/screens/invoice-receive.screen.ts +2 -0
- package/samples/recipes/event-sourcing/src/feature.ts +31 -0
- package/samples/recipes/handbook-knowledge/README.md +22 -0
- package/samples/recipes/handbook-knowledge/package.json +12 -0
- package/samples/recipes/handbook-knowledge/src/feature.ts +42 -0
- package/samples/recipes/list-table-options/README.md +9 -0
- package/samples/recipes/list-table-options/src/feature.ts +47 -2
- package/samples/recipes/managed-config/src/feature.ts +9 -1
- package/samples/recipes/record-detail-layout/README.md +7 -0
- package/samples/recipes/record-detail-layout/src/feature.ts +40 -2
- package/samples/recipes/record-detail-layout/src/order-board.ts +1 -0
- package/samples/recipes/secrets-demo/README.md +1 -1
- package/samples/recipes/secrets-demo/src/feature.ts +2 -0
- package/samples/recipes/signature/README.md +21 -0
- package/samples/recipes/signature/package.json +13 -0
- package/samples/recipes/signature/src/feature.ts +26 -0
- package/samples/recipes/writeform-section/README.md +4 -0
- package/samples/recipes/writeform-section/src/feature.ts +97 -0
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
import { configuredPiiSubjectKms } from "@cosmicdrift/kumiko-framework/crypto";
|
|
2
|
+
import { WritePurposes } from "@cosmicdrift/kumiko-framework/db";
|
|
3
|
+
import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
|
|
4
|
+
import {
|
|
5
|
+
createSystemUser,
|
|
6
|
+
type SessionUser,
|
|
7
|
+
type UserDataDeleteHook,
|
|
8
|
+
type UserDataExportHook,
|
|
9
|
+
type UserDataHookCtx,
|
|
10
|
+
} from "@cosmicdrift/kumiko-framework/engine";
|
|
11
|
+
import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
|
|
12
|
+
import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
|
|
13
|
+
import { collectErasureFailure, throwIfErasureFailed } from "../shared/index.ts";
|
|
14
|
+
import { resolveVerifiedUserEmail } from "../user/index.ts";
|
|
15
|
+
import { requestExecutor, signatureSignerTable, signerExecutor } from "./entity.ts";
|
|
16
|
+
import { deleteFileRef } from "./files.ts";
|
|
17
|
+
import { setRequestStatus } from "./lib.ts";
|
|
18
|
+
import { SIGNATURE_REQUEST_STATUS, SIGNATURE_SIGNER_ENTITY } from "./web/constants.ts";
|
|
19
|
+
|
|
20
|
+
const PII_DECRYPT_REASON = "signature:user-data";
|
|
21
|
+
const ANONYMIZED_NAME = "anonymized";
|
|
22
|
+
const ERASE_REASON = "signature:subject-forget";
|
|
23
|
+
|
|
24
|
+
type SignerRecord = Record<string, unknown>;
|
|
25
|
+
|
|
26
|
+
// A signer has no user account: the only link to a user is the signer's email, which is stored
|
|
27
|
+
// lowercase and findable by exact match. Without a verified email nothing matches.
|
|
28
|
+
async function findSignerRows(ctx: UserDataHookCtx): Promise<readonly SignerRecord[]> {
|
|
29
|
+
const email = await resolveVerifiedUserEmail(ctx, PII_DECRYPT_REASON);
|
|
30
|
+
if (email === null) return [];
|
|
31
|
+
return ctx.db.selectMany<SignerRecord>(signatureSignerTable, {
|
|
32
|
+
tenantId: ctx.tenantId,
|
|
33
|
+
email: email.toLowerCase(),
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function stringOrNull(value: unknown): string | null {
|
|
38
|
+
return typeof value === "string" ? value : null;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
// The signer's fields belong to the row's own record key, not to the user's key, so the user
|
|
42
|
+
// forget run does not shred them; and anonymizing only empties the current row, the old events
|
|
43
|
+
// still hold the ciphertext. Without a mounted KMS this erases nothing: record-owned fields stay
|
|
44
|
+
// plaintext framework-wide (see notes-history-user-data), so apps that need Art. 17 coverage mount one.
|
|
45
|
+
async function shredSignerKey(ctx: UserDataHookCtx, signerId: string): Promise<void> {
|
|
46
|
+
// skip: no KMS adapter mounted, nothing is encrypted per record
|
|
47
|
+
await configuredPiiSubjectKms()?.eraseKey(
|
|
48
|
+
{ kind: "record", entity: SIGNATURE_SIGNER_ENTITY, id: signerId },
|
|
49
|
+
{ requestId: ERASE_REASON, userId: ctx.userId, eraseReason: ERASE_REASON },
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export const signatureExportHook: UserDataExportHook = async (ctx) => {
|
|
54
|
+
const rows = await findSignerRows(ctx);
|
|
55
|
+
if (rows.length === 0) return null;
|
|
56
|
+
return {
|
|
57
|
+
entity: SIGNATURE_SIGNER_ENTITY,
|
|
58
|
+
rows: rows.map((row) => ({
|
|
59
|
+
requestId: row["requestId"],
|
|
60
|
+
name: row["name"],
|
|
61
|
+
role: row["role"],
|
|
62
|
+
status: row["status"],
|
|
63
|
+
method: row["method"],
|
|
64
|
+
signedAt: String(row["signedAt"] ?? ""),
|
|
65
|
+
signedFromIp: row["signedFromIp"],
|
|
66
|
+
signedUserAgent: row["signedUserAgent"],
|
|
67
|
+
declineReason: row["declineReason"],
|
|
68
|
+
})),
|
|
69
|
+
};
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
async function purgeSignatureImage(
|
|
73
|
+
ctx: UserDataHookCtx,
|
|
74
|
+
systemUser: SessionUser,
|
|
75
|
+
imageFileId: string,
|
|
76
|
+
): Promise<void> {
|
|
77
|
+
const [ref] = await ctx.db.selectMany<{ id: string; storageKey: string }>(fileRefsTable, {
|
|
78
|
+
id: imageFileId,
|
|
79
|
+
});
|
|
80
|
+
// skip: the image is already gone, nothing left to erase
|
|
81
|
+
if (ref === undefined) return;
|
|
82
|
+
const provider = await ctx.buildStorageProvider?.(ctx.tenantId);
|
|
83
|
+
if (!provider) {
|
|
84
|
+
throw new InternalError({
|
|
85
|
+
message: `[signature:user-data] no file storage resolvable, signature image ${imageFileId} cannot be erased`,
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
const failed = await deleteStoredFileAndDerivatives(ref.storageKey, provider, PII_DECRYPT_REASON);
|
|
89
|
+
if (failed.length > 0) {
|
|
90
|
+
throw new InternalError({
|
|
91
|
+
message: `[signature:user-data] ${failed.length} byte delete(s) failed for signature image ${imageFileId}`,
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
await deleteFileRef(ctx.db, systemUser, imageFileId);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
async function cancelUnfinishedRequest(
|
|
98
|
+
ctx: UserDataHookCtx,
|
|
99
|
+
systemUser: SessionUser,
|
|
100
|
+
requestId: string,
|
|
101
|
+
): Promise<void> {
|
|
102
|
+
const request = await requestExecutor.detail({ id: requestId }, systemUser, ctx.db);
|
|
103
|
+
const status = request?.status;
|
|
104
|
+
if (status !== SIGNATURE_REQUEST_STATUS.Open && status !== SIGNATURE_REQUEST_STATUS.AllSigned) {
|
|
105
|
+
return;
|
|
106
|
+
}
|
|
107
|
+
await setRequestStatus(ctx, systemUser, requestId, status, {
|
|
108
|
+
status: SIGNATURE_REQUEST_STATUS.Cancelled,
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
// Erasure wins over retention for the person's own data: name, email, drawn image, IP address,
|
|
113
|
+
// user agent and refusal reason are removed (strategy delete: the whole row). What stays is the
|
|
114
|
+
// completed PDF with its signature page, which belongs to the request's owner as proof of the
|
|
115
|
+
// contract (Art. 17(3)(e) GDPR), and the row's status and timestamps under "anonymize". A forgotten
|
|
116
|
+
// signer would let the others complete the request without them (delete) or leave an all-signed
|
|
117
|
+
// request without the image it needs (anonymize), so an open or all-signed request is cancelled.
|
|
118
|
+
export const signatureDeleteHook: UserDataDeleteHook = async (ctx, strategy) => {
|
|
119
|
+
const systemUser = createSystemUser(ctx.tenantId);
|
|
120
|
+
const failures: string[] = [];
|
|
121
|
+
for (const row of await findSignerRows(ctx)) {
|
|
122
|
+
const id = stringOrNull(row["id"]);
|
|
123
|
+
if (id === null) continue;
|
|
124
|
+
const imageFileId = stringOrNull(row["imageFileId"]);
|
|
125
|
+
if (imageFileId !== null) await purgeSignatureImage(ctx, systemUser, imageFileId);
|
|
126
|
+
const requestId = stringOrNull(row["requestId"]);
|
|
127
|
+
if (strategy === "delete") {
|
|
128
|
+
const forgotten = await signerExecutor.forget({ id }, systemUser, ctx.db);
|
|
129
|
+
collectErasureFailure(forgotten, SIGNATURE_SIGNER_ENTITY, id, failures);
|
|
130
|
+
if (forgotten.isSuccess && requestId !== null) {
|
|
131
|
+
await cancelUnfinishedRequest(ctx, systemUser, requestId);
|
|
132
|
+
}
|
|
133
|
+
if (forgotten.isSuccess) await shredSignerKey(ctx, id);
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
const anonymized = await signerExecutor.update(
|
|
137
|
+
{
|
|
138
|
+
id,
|
|
139
|
+
changes: {
|
|
140
|
+
name: ANONYMIZED_NAME,
|
|
141
|
+
email: null,
|
|
142
|
+
imageFileId: null,
|
|
143
|
+
signedFromIp: null,
|
|
144
|
+
signedUserAgent: null,
|
|
145
|
+
declineReason: null,
|
|
146
|
+
linkAnchor: null,
|
|
147
|
+
},
|
|
148
|
+
},
|
|
149
|
+
systemUser,
|
|
150
|
+
ctx.db,
|
|
151
|
+
{ skipOptimisticLock: true, writePurpose: WritePurposes.erasure },
|
|
152
|
+
);
|
|
153
|
+
collectErasureFailure(anonymized, SIGNATURE_SIGNER_ENTITY, id, failures);
|
|
154
|
+
if (!anonymized.isSuccess) continue;
|
|
155
|
+
if (requestId !== null) await cancelUnfinishedRequest(ctx, systemUser, requestId);
|
|
156
|
+
await shredSignerKey(ctx, id);
|
|
157
|
+
}
|
|
158
|
+
throwIfErasureFailed(failures);
|
|
159
|
+
};
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
// Pure string constants, safe for browser code (static-sign imports this file).
|
|
2
|
+
export const SIGNATURE_FEATURE = "signature" as const;
|
|
3
|
+
|
|
4
|
+
export const SIGNATURE_REQUEST_ENTITY = "signatureRequest" as const;
|
|
5
|
+
export const SIGNATURE_SIGNER_ENTITY = "signatureSigner" as const;
|
|
6
|
+
|
|
7
|
+
export const SIGNATURE_LEVEL = {
|
|
8
|
+
Simple: "simple",
|
|
9
|
+
} as const;
|
|
10
|
+
|
|
11
|
+
export type SignatureLevel = (typeof SIGNATURE_LEVEL)[keyof typeof SIGNATURE_LEVEL];
|
|
12
|
+
|
|
13
|
+
export const SIGNATURE_REQUEST_STATUS = {
|
|
14
|
+
Open: "open",
|
|
15
|
+
AllSigned: "all-signed",
|
|
16
|
+
Completed: "completed",
|
|
17
|
+
Declined: "declined",
|
|
18
|
+
Expired: "expired",
|
|
19
|
+
Cancelled: "cancelled",
|
|
20
|
+
} as const;
|
|
21
|
+
|
|
22
|
+
export type SignatureRequestStatus =
|
|
23
|
+
(typeof SIGNATURE_REQUEST_STATUS)[keyof typeof SIGNATURE_REQUEST_STATUS];
|
|
24
|
+
|
|
25
|
+
export const SIGNATURE_SIGNER_STATUS = {
|
|
26
|
+
Pending: "pending",
|
|
27
|
+
Viewed: "viewed",
|
|
28
|
+
Signed: "signed",
|
|
29
|
+
Declined: "declined",
|
|
30
|
+
} as const;
|
|
31
|
+
|
|
32
|
+
export type SignatureSignerStatus =
|
|
33
|
+
(typeof SIGNATURE_SIGNER_STATUS)[keyof typeof SIGNATURE_SIGNER_STATUS];
|
|
34
|
+
|
|
35
|
+
export const SIGNATURE_METHOD = {
|
|
36
|
+
InPerson: "in-person",
|
|
37
|
+
Link: "link",
|
|
38
|
+
} as const;
|
|
39
|
+
|
|
40
|
+
export type SignatureMethod = (typeof SIGNATURE_METHOD)[keyof typeof SIGNATURE_METHOD];
|
|
41
|
+
|
|
42
|
+
export const SignatureHandlers = {
|
|
43
|
+
request: `${SIGNATURE_FEATURE}:write:request`,
|
|
44
|
+
signInPerson: `${SIGNATURE_FEATURE}:write:sign-in-person`,
|
|
45
|
+
issueLink: `${SIGNATURE_FEATURE}:write:issue-link`,
|
|
46
|
+
revokeLink: `${SIGNATURE_FEATURE}:write:revoke-link`,
|
|
47
|
+
cancel: `${SIGNATURE_FEATURE}:write:cancel`,
|
|
48
|
+
openByLink: `${SIGNATURE_FEATURE}:write:open-by-link`,
|
|
49
|
+
signByLink: `${SIGNATURE_FEATURE}:write:sign-by-link`,
|
|
50
|
+
declineByLink: `${SIGNATURE_FEATURE}:write:decline-by-link`,
|
|
51
|
+
} as const;
|
|
52
|
+
|
|
53
|
+
export const SignatureQueries = {
|
|
54
|
+
list: `${SIGNATURE_FEATURE}:query:signature-request:list`,
|
|
55
|
+
detail: `${SIGNATURE_FEATURE}:query:signature-request:detail`,
|
|
56
|
+
signerList: `${SIGNATURE_FEATURE}:query:signature-signer:list`,
|
|
57
|
+
} as const;
|
|
58
|
+
|
|
59
|
+
export const SignatureJobs = {
|
|
60
|
+
sweep: `${SIGNATURE_FEATURE}:job:sweep`,
|
|
61
|
+
} as const;
|
|
62
|
+
|
|
63
|
+
export const SIGNATURE_EVENT_SHORT = {
|
|
64
|
+
completed: "completed",
|
|
65
|
+
declined: "declined",
|
|
66
|
+
expired: "expired",
|
|
67
|
+
} as const;
|
|
68
|
+
|
|
69
|
+
export const SignatureEvents = {
|
|
70
|
+
completed: `${SIGNATURE_FEATURE}:event:${SIGNATURE_EVENT_SHORT.completed}`,
|
|
71
|
+
declined: `${SIGNATURE_FEATURE}:event:${SIGNATURE_EVENT_SHORT.declined}`,
|
|
72
|
+
expired: `${SIGNATURE_FEATURE}:event:${SIGNATURE_EVENT_SHORT.expired}`,
|
|
73
|
+
} as const;
|
|
74
|
+
|
|
75
|
+
// Every link rejection (forged, expired, revoked, used up, already signed) carries this reason, so
|
|
76
|
+
// a caller cannot tell the cases apart.
|
|
77
|
+
export const SIGNATURE_INVALID_LINK_REASON = "invalid_or_expired_link";
|
|
78
|
+
|
|
79
|
+
export const SIGNATURE_INVALID_IMAGE_REASON = "invalid_signature_image";
|
|
80
|
+
|
|
81
|
+
export const SIGNATURE_LINK_TTL_DAYS = 14;
|
|
82
|
+
export const SIGNATURE_MAX_LINK_OPENS = 20;
|
|
83
|
+
export const SIGNATURE_DEFAULT_VALIDITY_DAYS = 14;
|
|
84
|
+
|
|
85
|
+
export const SignatureInternalHandlers = {
|
|
86
|
+
linkOpen: `${SIGNATURE_FEATURE}:write:link-open`,
|
|
87
|
+
linkSign: `${SIGNATURE_FEATURE}:write:link-sign`,
|
|
88
|
+
linkDecline: `${SIGNATURE_FEATURE}:write:link-decline`,
|
|
89
|
+
finish: `${SIGNATURE_FEATURE}:write:finish`,
|
|
90
|
+
expire: `${SIGNATURE_FEATURE}:write:expire`,
|
|
91
|
+
reconcile: `${SIGNATURE_FEATURE}:write:reconcile`,
|
|
92
|
+
} as const;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
export {
|
|
2
|
+
SIGNATURE_DEFAULT_VALIDITY_DAYS,
|
|
3
|
+
SIGNATURE_EVENT_SHORT,
|
|
4
|
+
SIGNATURE_FEATURE,
|
|
5
|
+
SIGNATURE_INVALID_IMAGE_REASON,
|
|
6
|
+
SIGNATURE_INVALID_LINK_REASON,
|
|
7
|
+
SIGNATURE_LEVEL,
|
|
8
|
+
SIGNATURE_LINK_TTL_DAYS,
|
|
9
|
+
SIGNATURE_MAX_LINK_OPENS,
|
|
10
|
+
SIGNATURE_METHOD,
|
|
11
|
+
SIGNATURE_REQUEST_ENTITY,
|
|
12
|
+
SIGNATURE_REQUEST_STATUS,
|
|
13
|
+
SIGNATURE_SIGNER_ENTITY,
|
|
14
|
+
SIGNATURE_SIGNER_STATUS,
|
|
15
|
+
SignatureEvents,
|
|
16
|
+
SignatureHandlers,
|
|
17
|
+
SignatureInternalHandlers,
|
|
18
|
+
SignatureJobs,
|
|
19
|
+
type SignatureLevel,
|
|
20
|
+
type SignatureMethod,
|
|
21
|
+
SignatureQueries,
|
|
22
|
+
type SignatureRequestStatus,
|
|
23
|
+
type SignatureSignerStatus,
|
|
24
|
+
} from "./constants.ts";
|
|
25
|
+
export type { SignaturePad as SignaturePadController, SignaturePadOptions } from "./pad.ts";
|
|
26
|
+
export {
|
|
27
|
+
DEFAULT_SIGNATURE_PAD_LABELS,
|
|
28
|
+
SignaturePad,
|
|
29
|
+
type SignaturePadLabels,
|
|
30
|
+
type SignaturePadProps,
|
|
31
|
+
} from "./signature-pad.tsx";
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
// Framework-free signature field: Pointer Events (finger, pen, mouse) on a canvas. Imports nothing,
|
|
2
|
+
// so the static-sign entry stays free of React and of any runtime dependency.
|
|
3
|
+
|
|
4
|
+
export type SignaturePadCanvas = Pick<
|
|
5
|
+
HTMLCanvasElement,
|
|
6
|
+
| "width"
|
|
7
|
+
| "height"
|
|
8
|
+
| "addEventListener"
|
|
9
|
+
| "removeEventListener"
|
|
10
|
+
| "getBoundingClientRect"
|
|
11
|
+
| "getContext"
|
|
12
|
+
| "toBlob"
|
|
13
|
+
| "setPointerCapture"
|
|
14
|
+
| "releasePointerCapture"
|
|
15
|
+
> & { readonly style: Pick<CSSStyleDeclaration, "touchAction"> };
|
|
16
|
+
|
|
17
|
+
export type SignaturePadOptions = {
|
|
18
|
+
/** Stroke width in canvas pixels. Default 3. */
|
|
19
|
+
readonly lineWidth?: number;
|
|
20
|
+
/** Stroke colour. Default near-black. */
|
|
21
|
+
readonly strokeStyle?: string;
|
|
22
|
+
/** Called whenever the field switches between empty and drawn. */
|
|
23
|
+
readonly onChange?: (isEmpty: boolean) => void;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
export type SignaturePad = {
|
|
27
|
+
readonly clear: () => void;
|
|
28
|
+
readonly isEmpty: () => boolean;
|
|
29
|
+
/** PNG with transparent background as base64 without the data-URL prefix. */
|
|
30
|
+
readonly toPngBase64: () => Promise<string>;
|
|
31
|
+
readonly destroy: () => void;
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
const DEFAULT_LINE_WIDTH = 3;
|
|
35
|
+
const DEFAULT_STROKE_STYLE = "#111111";
|
|
36
|
+
const BASE64_CHUNK_SIZE = 0x8000;
|
|
37
|
+
|
|
38
|
+
export function bytesToBase64(bytes: Uint8Array): string {
|
|
39
|
+
let binary = "";
|
|
40
|
+
for (let offset = 0; offset < bytes.length; offset += BASE64_CHUNK_SIZE) {
|
|
41
|
+
binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_CHUNK_SIZE));
|
|
42
|
+
}
|
|
43
|
+
return btoa(binary);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
type Point = { readonly x: number; readonly y: number };
|
|
47
|
+
|
|
48
|
+
// Closures of the pad need the non-null context; narrowing a const does not carry into them.
|
|
49
|
+
function requireContext(canvas: SignaturePadCanvas): CanvasRenderingContext2D {
|
|
50
|
+
const context = canvas.getContext("2d");
|
|
51
|
+
if (context === null) throw new Error("createSignaturePad: the canvas has no 2d context");
|
|
52
|
+
return context;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
export function createSignaturePad(
|
|
56
|
+
canvas: SignaturePadCanvas,
|
|
57
|
+
options: SignaturePadOptions = {},
|
|
58
|
+
): SignaturePad {
|
|
59
|
+
const context = requireContext(canvas);
|
|
60
|
+
const lineWidth = options.lineWidth ?? DEFAULT_LINE_WIDTH;
|
|
61
|
+
context.lineWidth = lineWidth;
|
|
62
|
+
context.lineCap = "round";
|
|
63
|
+
context.lineJoin = "round";
|
|
64
|
+
context.strokeStyle = options.strokeStyle ?? DEFAULT_STROKE_STYLE;
|
|
65
|
+
context.fillStyle = options.strokeStyle ?? DEFAULT_STROKE_STYLE;
|
|
66
|
+
canvas.style.touchAction = "none";
|
|
67
|
+
|
|
68
|
+
let drawnAny = false;
|
|
69
|
+
let activePointerId: number | null = null;
|
|
70
|
+
let lastPoint: Point | null = null;
|
|
71
|
+
|
|
72
|
+
function setDrawn(next: boolean): void {
|
|
73
|
+
if (drawnAny === next) return;
|
|
74
|
+
drawnAny = next;
|
|
75
|
+
options.onChange?.(!next);
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
// The canvas may be displayed at another size than its pixel size (CSS scaling).
|
|
79
|
+
function pointOf(event: PointerEvent): Point {
|
|
80
|
+
const rect = canvas.getBoundingClientRect();
|
|
81
|
+
const scaleX = rect.width > 0 ? canvas.width / rect.width : 1;
|
|
82
|
+
const scaleY = rect.height > 0 ? canvas.height / rect.height : 1;
|
|
83
|
+
return { x: (event.clientX - rect.left) * scaleX, y: (event.clientY - rect.top) * scaleY };
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
function onPointerDown(event: PointerEvent): void {
|
|
87
|
+
if (activePointerId !== null) return;
|
|
88
|
+
activePointerId = event.pointerId;
|
|
89
|
+
canvas.setPointerCapture(event.pointerId);
|
|
90
|
+
const point = pointOf(event);
|
|
91
|
+
lastPoint = point;
|
|
92
|
+
context.beginPath();
|
|
93
|
+
context.arc(point.x, point.y, lineWidth / 2, 0, Math.PI * 2);
|
|
94
|
+
context.fill();
|
|
95
|
+
setDrawn(true);
|
|
96
|
+
event.preventDefault();
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
function onPointerMove(event: PointerEvent): void {
|
|
100
|
+
if (event.pointerId !== activePointerId || lastPoint === null) return;
|
|
101
|
+
const point = pointOf(event);
|
|
102
|
+
context.beginPath();
|
|
103
|
+
context.moveTo(lastPoint.x, lastPoint.y);
|
|
104
|
+
context.lineTo(point.x, point.y);
|
|
105
|
+
context.stroke();
|
|
106
|
+
lastPoint = point;
|
|
107
|
+
event.preventDefault();
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
function onPointerEnd(event: PointerEvent): void {
|
|
111
|
+
if (event.pointerId !== activePointerId) return;
|
|
112
|
+
canvas.releasePointerCapture(event.pointerId);
|
|
113
|
+
activePointerId = null;
|
|
114
|
+
lastPoint = null;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
canvas.addEventListener("pointerdown", onPointerDown);
|
|
118
|
+
canvas.addEventListener("pointermove", onPointerMove);
|
|
119
|
+
canvas.addEventListener("pointerup", onPointerEnd);
|
|
120
|
+
canvas.addEventListener("pointercancel", onPointerEnd);
|
|
121
|
+
|
|
122
|
+
return {
|
|
123
|
+
clear: () => {
|
|
124
|
+
context.clearRect(0, 0, canvas.width, canvas.height);
|
|
125
|
+
setDrawn(false);
|
|
126
|
+
},
|
|
127
|
+
isEmpty: () => !drawnAny,
|
|
128
|
+
toPngBase64: () =>
|
|
129
|
+
new Promise((resolve, reject) => {
|
|
130
|
+
canvas.toBlob((blob) => {
|
|
131
|
+
if (blob === null) {
|
|
132
|
+
reject(new Error("createSignaturePad: the canvas could not be exported as PNG"));
|
|
133
|
+
return;
|
|
134
|
+
}
|
|
135
|
+
blob
|
|
136
|
+
.arrayBuffer()
|
|
137
|
+
.then((buffer) => resolve(bytesToBase64(new Uint8Array(buffer))), reject);
|
|
138
|
+
}, "image/png");
|
|
139
|
+
}),
|
|
140
|
+
destroy: () => {
|
|
141
|
+
canvas.removeEventListener("pointerdown", onPointerDown);
|
|
142
|
+
canvas.removeEventListener("pointermove", onPointerMove);
|
|
143
|
+
canvas.removeEventListener("pointerup", onPointerEnd);
|
|
144
|
+
canvas.removeEventListener("pointercancel", onPointerEnd);
|
|
145
|
+
},
|
|
146
|
+
};
|
|
147
|
+
}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
|
|
2
|
+
import { useCallback, useRef, useState } from "react";
|
|
3
|
+
import { createSignaturePad, type SignaturePad as SignaturePadController } from "./pad.ts";
|
|
4
|
+
|
|
5
|
+
export type SignaturePadLabels = {
|
|
6
|
+
readonly fieldLabel: string;
|
|
7
|
+
readonly clear: string;
|
|
8
|
+
readonly signOnPaper: string;
|
|
9
|
+
};
|
|
10
|
+
|
|
11
|
+
export const DEFAULT_SIGNATURE_PAD_LABELS: SignaturePadLabels = {
|
|
12
|
+
fieldLabel: "Signature field: draw your signature with finger, pen or mouse",
|
|
13
|
+
clear: "Clear",
|
|
14
|
+
signOnPaper: "Sign on paper instead",
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
export type SignaturePadProps = {
|
|
18
|
+
/** Gets the controller once the canvas is mounted and null on unmount; read `toPngBase64()` from it on submit. Keep it referentially stable, a new function recreates the field. */
|
|
19
|
+
readonly onPadReady: (pad: SignaturePadController | null) => void;
|
|
20
|
+
/** Same stability requirement as `onPadReady`. */
|
|
21
|
+
readonly onChange?: (isEmpty: boolean) => void;
|
|
22
|
+
/** Shows the "sign on paper" exit; the signer who cannot draw must always have a way out. */
|
|
23
|
+
readonly onSignOnPaper?: () => void;
|
|
24
|
+
readonly labels?: Partial<SignaturePadLabels>;
|
|
25
|
+
readonly width?: number;
|
|
26
|
+
readonly height?: number;
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
const DEFAULT_WIDTH = 600;
|
|
30
|
+
const DEFAULT_HEIGHT = 240;
|
|
31
|
+
|
|
32
|
+
// Drawing needs a pointer; everything else (clear, the paper exit) is a plain focusable button.
|
|
33
|
+
// The pad lives in a callback ref instead of an effect: it follows the canvas element's mount and unmount.
|
|
34
|
+
export function SignaturePad(props: SignaturePadProps) {
|
|
35
|
+
const { Button } = usePrimitives();
|
|
36
|
+
const labels = { ...DEFAULT_SIGNATURE_PAD_LABELS, ...props.labels };
|
|
37
|
+
const padRef = useRef<SignaturePadController | null>(null);
|
|
38
|
+
const [isEmpty, setIsEmpty] = useState(true);
|
|
39
|
+
const { onPadReady, onChange } = props;
|
|
40
|
+
|
|
41
|
+
const mountPad = useCallback(
|
|
42
|
+
(canvas: HTMLCanvasElement) => {
|
|
43
|
+
const pad = createSignaturePad(canvas, {
|
|
44
|
+
onChange: (empty) => {
|
|
45
|
+
setIsEmpty(empty);
|
|
46
|
+
onChange?.(empty);
|
|
47
|
+
},
|
|
48
|
+
});
|
|
49
|
+
padRef.current = pad;
|
|
50
|
+
onPadReady(pad);
|
|
51
|
+
return () => {
|
|
52
|
+
pad.destroy();
|
|
53
|
+
padRef.current = null;
|
|
54
|
+
onPadReady(null);
|
|
55
|
+
};
|
|
56
|
+
},
|
|
57
|
+
[onPadReady, onChange],
|
|
58
|
+
);
|
|
59
|
+
|
|
60
|
+
return (
|
|
61
|
+
<div className="flex flex-col gap-2">
|
|
62
|
+
<canvas
|
|
63
|
+
ref={mountPad}
|
|
64
|
+
width={props.width ?? DEFAULT_WIDTH}
|
|
65
|
+
height={props.height ?? DEFAULT_HEIGHT}
|
|
66
|
+
role="img"
|
|
67
|
+
aria-label={labels.fieldLabel}
|
|
68
|
+
className="w-full rounded border border-input bg-white"
|
|
69
|
+
/>
|
|
70
|
+
<div className="flex gap-2">
|
|
71
|
+
<Button variant="secondary" disabled={isEmpty} onClick={() => padRef.current?.clear()}>
|
|
72
|
+
{labels.clear}
|
|
73
|
+
</Button>
|
|
74
|
+
{props.onSignOnPaper === undefined ? null : (
|
|
75
|
+
<Button variant="ghost" onClick={props.onSignOnPaper}>
|
|
76
|
+
{labels.signOnPaper}
|
|
77
|
+
</Button>
|
|
78
|
+
)}
|
|
79
|
+
</div>
|
|
80
|
+
</div>
|
|
81
|
+
);
|
|
82
|
+
}
|
|
@@ -1,4 +1,10 @@
|
|
|
1
1
|
[
|
|
2
|
+
{
|
|
3
|
+
"version": "0.416.0",
|
|
4
|
+
"type": "improvement",
|
|
5
|
+
"title": "Stripe checkout can accept promotion codes",
|
|
6
|
+
"detail": "The new option `allowPromotionCodes` sets `allow_promotion_codes` on every Checkout Session of the app, in subscription and payment mode. Coupons and promotion codes are created in the Stripe dashboard. Default false, so existing checkouts show no code field. The consumer-protection confirmation mail still shows the catalog price captured at consent, not the discounted amount."
|
|
7
|
+
},
|
|
2
8
|
{
|
|
3
9
|
"version": "0.415.0",
|
|
4
10
|
"type": "fix",
|
|
@@ -132,6 +132,12 @@ export type SubscriptionStripeOptions = {
|
|
|
132
132
|
* mode:"subscription" — Stripe rejects invoice_creation there; the
|
|
133
133
|
* subscription's own invoicing covers it. */
|
|
134
134
|
readonly paymentInvoiceCreation?: boolean;
|
|
135
|
+
/** Shows Stripe's promotion-code field in every checkout of this app.
|
|
136
|
+
* Default false, because the field shows even when no code exists. Codes
|
|
137
|
+
* and coupons are created in the Stripe dashboard, not in the app. The
|
|
138
|
+
* consumer-protection confirmation mail shows the catalog price captured
|
|
139
|
+
* at consent, not the discounted amount. */
|
|
140
|
+
readonly allowPromotionCodes?: boolean;
|
|
135
141
|
/** Allowlist of Stripe price-ids a mode:"payment" (one-off) checkout may
|
|
136
142
|
* target — checkout-core's `openCheckout` rejects any other priceId as
|
|
137
143
|
* `unknown_price`. App-specific and empty by default: without an
|
|
@@ -241,6 +247,9 @@ export function createSubscriptionStripeFeature(
|
|
|
241
247
|
...(options.paymentInvoiceCreation !== undefined && {
|
|
242
248
|
paymentInvoiceCreation: options.paymentInvoiceCreation,
|
|
243
249
|
}),
|
|
250
|
+
...(options.allowPromotionCodes !== undefined && {
|
|
251
|
+
allowPromotionCodes: options.allowPromotionCodes,
|
|
252
|
+
}),
|
|
244
253
|
}),
|
|
245
254
|
createPortalSession: createStripePortalSession(runtimes.ctx),
|
|
246
255
|
cancelSubscription: createStripeCancelSubscription(runtimes.ctx),
|
|
@@ -45,6 +45,8 @@ export type StripeCheckoutSessionRuntimeOptions = {
|
|
|
45
45
|
/** Whether a mode:"payment" checkout gets a Stripe invoice. Default true.
|
|
46
46
|
* Never applied in mode:"subscription" — Stripe rejects invoice_creation there. */
|
|
47
47
|
readonly paymentInvoiceCreation?: boolean;
|
|
48
|
+
/** Shows Stripe's promotion-code field in checkout. Default false. */
|
|
49
|
+
readonly allowPromotionCodes?: boolean;
|
|
48
50
|
};
|
|
49
51
|
|
|
50
52
|
// Stripe's own Locale union also accepts arbitrary strings, so the known set
|
|
@@ -114,7 +116,10 @@ function isUnknownCustomerStripeError(
|
|
|
114
116
|
|
|
115
117
|
export function createStripeCheckoutSession(
|
|
116
118
|
runtime: StripeCtxRuntime,
|
|
117
|
-
{
|
|
119
|
+
{
|
|
120
|
+
paymentInvoiceCreation = true,
|
|
121
|
+
allowPromotionCodes = false,
|
|
122
|
+
}: StripeCheckoutSessionRuntimeOptions = {},
|
|
118
123
|
) {
|
|
119
124
|
return async (
|
|
120
125
|
ctx: HandlerContext,
|
|
@@ -138,6 +143,7 @@ export function createStripeCheckoutSession(
|
|
|
138
143
|
success_url: options.successUrl,
|
|
139
144
|
cancel_url: options.cancelUrl,
|
|
140
145
|
submit_type: "pay",
|
|
146
|
+
...(allowPromotionCodes && { allow_promotion_codes: true }),
|
|
141
147
|
...(options.locale && { locale: mapAppLocaleToStripeLocale(options.locale) }),
|
|
142
148
|
...(options.submitMessage && {
|
|
143
149
|
custom_text: {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
|
|
3
|
-
"featureCount":
|
|
3
|
+
"featureCount": 96,
|
|
4
4
|
"features": [
|
|
5
5
|
{
|
|
6
6
|
"name": "account-security",
|
|
@@ -1443,6 +1443,25 @@
|
|
|
1443
1443
|
"secrets": [],
|
|
1444
1444
|
"writeHandlers": []
|
|
1445
1445
|
},
|
|
1446
|
+
{
|
|
1447
|
+
"name": "handbook-knowledge",
|
|
1448
|
+
"description": "Gives the AI agent the app's handbook as two read-only query tools: `list-pages` returns the catalog of task and screen pages with the questions each answers, `read-page` returns one page in the caller's language with a fallback to the default language and a fixed length cap. The pages come from a build-time JSON (`kumiko handbuch knowledge`), so no table, projection or search index is involved and the handbook text stays public content.",
|
|
1449
|
+
"toggleableDefault": null,
|
|
1450
|
+
"requires": [],
|
|
1451
|
+
"optionalRequires": [],
|
|
1452
|
+
"configReads": [],
|
|
1453
|
+
"exposesApis": [],
|
|
1454
|
+
"usesApis": [],
|
|
1455
|
+
"extensionsUsed": [],
|
|
1456
|
+
"configKeys": [],
|
|
1457
|
+
"secrets": [],
|
|
1458
|
+
"writeHandlers": [],
|
|
1459
|
+
"uiHints": {
|
|
1460
|
+
"displayLabel": "Handbook Knowledge",
|
|
1461
|
+
"category": "ai",
|
|
1462
|
+
"recommended": false
|
|
1463
|
+
}
|
|
1464
|
+
},
|
|
1446
1465
|
{
|
|
1447
1466
|
"name": "helpdesk",
|
|
1448
1467
|
"description": "Helpdesk inbox: an anonymous browser client (GET /helpdesk/client.js) submits questions, contact requests, bug reports and wishes behind a honeypot, a minimum submit time and a single-use proof-of-work challenge; signed-in users file reports from the admin. Every request is stored platform-wide and every SystemAdmin is notified by mail, optionally also in a Telegram chat (option `telegram`, off by default); the notification names only the kind, the app and a link, never name, address, phone, subject or message, because mail and Telegram cannot be shredded. SystemAdmins reply by mail (Reply-To set, attachments, quoting the original) and mark requests done; a website sender gets a fixed acknowledgement, a signed-in reporter a copy and an in-app note. Personal data is crypto-shredding-ready and the EXT_USER_DATA hooks export and erase a user's requests.",
|
|
@@ -2658,6 +2677,49 @@
|
|
|
2658
2677
|
"recommended": false
|
|
2659
2678
|
}
|
|
2660
2679
|
},
|
|
2680
|
+
{
|
|
2681
|
+
"name": "signature",
|
|
2682
|
+
"description": "Signature requests: a signed-in user asks several people to sign one PDF of the tenant. Each signer draws a signature on a display in person or through a link in the URL fragment (14 days, limited opens, revocable, single-use, one answer for every rejection). The last signature moves the request to all-signed; a job renders a signature page through the injected print function, appends it to the unchanged original and completes the request. Events completed, declined and expired report the outcome; signer name, email, image, IP and user agent are personal data.",
|
|
2683
|
+
"toggleableDefault": null,
|
|
2684
|
+
"adoptsBundledLists": true,
|
|
2685
|
+
"requires": [
|
|
2686
|
+
"files",
|
|
2687
|
+
"user-data-rights"
|
|
2688
|
+
],
|
|
2689
|
+
"optionalRequires": [],
|
|
2690
|
+
"configReads": [],
|
|
2691
|
+
"exposesApis": [],
|
|
2692
|
+
"usesApis": [],
|
|
2693
|
+
"extensionsUsed": [
|
|
2694
|
+
{
|
|
2695
|
+
"extensionName": "userData",
|
|
2696
|
+
"entityName": "signatureSigner"
|
|
2697
|
+
}
|
|
2698
|
+
],
|
|
2699
|
+
"configKeys": [],
|
|
2700
|
+
"secrets": [],
|
|
2701
|
+
"writeHandlers": [
|
|
2702
|
+
"signature:write:cancel",
|
|
2703
|
+
"signature:write:decline-by-link",
|
|
2704
|
+
"signature:write:expire",
|
|
2705
|
+
"signature:write:finish",
|
|
2706
|
+
"signature:write:issue-link",
|
|
2707
|
+
"signature:write:link-decline",
|
|
2708
|
+
"signature:write:link-open",
|
|
2709
|
+
"signature:write:link-sign",
|
|
2710
|
+
"signature:write:open-by-link",
|
|
2711
|
+
"signature:write:reconcile",
|
|
2712
|
+
"signature:write:request",
|
|
2713
|
+
"signature:write:revoke-link",
|
|
2714
|
+
"signature:write:sign-by-link",
|
|
2715
|
+
"signature:write:sign-in-person"
|
|
2716
|
+
],
|
|
2717
|
+
"uiHints": {
|
|
2718
|
+
"displayLabel": "Signatures",
|
|
2719
|
+
"category": "data",
|
|
2720
|
+
"recommended": false
|
|
2721
|
+
}
|
|
2722
|
+
},
|
|
2661
2723
|
{
|
|
2662
2724
|
"name": "step-dispatcher",
|
|
2663
2725
|
"description": "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. An `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event enqueues one `step-dispatcher:job:deliver` BullMQ job per dispatch (Redis carries only the stream id and tenant, never the request payload). The job performs the actual HTTP or mail delivery and appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream, so the outcome is recorded in the event log without a separate status table. Transient failures (network error, timeout, 5xx, 408, 429, any mail adapter failure) are retried 3 times with exponential backoff; the outcome is recorded after the final attempt and the payload key is erased only then. A request that still has no outcome after 24 hours (job stalled or lost, or its final attempt could not record one) is closed by the daily `step-dispatcher:job:sweep-abandoned` cron (it pages through all such requests; requests that already have an outcome are not swept) with a generic `dispatch-failed` event and its payload key is erased. Permanent failures (invalid url, blocked host, other 4xx, unavailable auth secret) are recorded immediately. At most 2 deliveries per tenant run at once (`maxPerTenant` with `onLimit: \"defer\"`), so a slow receiver of one tenant does not delay other tenants. Requires a job runner (Redis) and a worker consuming the job's default `worker` lane; without a job runner the projection fails loudly. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across retries and redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.",
|