@cosmicdrift/kumiko-samples 0.415.0 → 0.416.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.
Files changed (62) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +21 -1
  3. package/packages/bundled-features/src/agent-tools/changes.json +6 -0
  4. package/packages/bundled-features/src/agent-tools/tool-catalog.ts +20 -1
  5. package/packages/bundled-features/src/agent-tools/tool-dispatch.ts +19 -5
  6. package/packages/bundled-features/src/channel-whatsapp/changes.json +6 -0
  7. package/packages/bundled-features/src/channel-whatsapp/constants.ts +1 -0
  8. package/packages/bundled-features/src/channel-whatsapp/graph-client.ts +37 -1
  9. package/packages/bundled-features/src/handbook-knowledge/README.md +64 -0
  10. package/packages/bundled-features/src/handbook-knowledge/changes.json +8 -0
  11. package/packages/bundled-features/src/handbook-knowledge/constants.ts +8 -0
  12. package/packages/bundled-features/src/handbook-knowledge/feature.ts +34 -0
  13. package/packages/bundled-features/src/handbook-knowledge/handbook-index.ts +66 -0
  14. package/packages/bundled-features/src/handbook-knowledge/handlers.ts +77 -0
  15. package/packages/bundled-features/src/handbook-knowledge/index.ts +10 -0
  16. package/packages/bundled-features/src/signature/README.md +59 -0
  17. package/packages/bundled-features/src/signature/changes.json +15 -0
  18. package/packages/bundled-features/src/signature/entity.ts +192 -0
  19. package/packages/bundled-features/src/signature/feature.ts +125 -0
  20. package/packages/bundled-features/src/signature/files.ts +107 -0
  21. package/packages/bundled-features/src/signature/grant.ts +79 -0
  22. package/packages/bundled-features/src/signature/handlers/anonymous.write.ts +88 -0
  23. package/packages/bundled-features/src/signature/handlers/cancel.write.ts +40 -0
  24. package/packages/bundled-features/src/signature/handlers/issue-link.write.ts +72 -0
  25. package/packages/bundled-features/src/signature/handlers/lifecycle.write.ts +99 -0
  26. package/packages/bundled-features/src/signature/handlers/link-internal.write.ts +261 -0
  27. package/packages/bundled-features/src/signature/handlers/request.write.ts +86 -0
  28. package/packages/bundled-features/src/signature/handlers/revoke-link.write.ts +23 -0
  29. package/packages/bundled-features/src/signature/handlers/sign-in-person.write.ts +69 -0
  30. package/packages/bundled-features/src/signature/i18n.ts +52 -0
  31. package/packages/bundled-features/src/signature/index.ts +33 -0
  32. package/packages/bundled-features/src/signature/lib.ts +125 -0
  33. package/packages/bundled-features/src/signature/options.ts +49 -0
  34. package/packages/bundled-features/src/signature/payloads.ts +71 -0
  35. package/packages/bundled-features/src/signature/png.ts +169 -0
  36. package/packages/bundled-features/src/signature/screens.ts +115 -0
  37. package/packages/bundled-features/src/signature/signature-page.ts +93 -0
  38. package/packages/bundled-features/src/signature/signing.ts +77 -0
  39. package/packages/bundled-features/src/signature/static-sign.ts +98 -0
  40. package/packages/bundled-features/src/signature/sweep.ts +161 -0
  41. package/packages/bundled-features/src/signature/user-data.ts +159 -0
  42. package/packages/bundled-features/src/signature/web/constants.ts +92 -0
  43. package/packages/bundled-features/src/signature/web/index.ts +31 -0
  44. package/packages/bundled-features/src/signature/web/pad.ts +147 -0
  45. package/packages/bundled-features/src/signature/web/signature-pad.tsx +82 -0
  46. package/packages/bundled-features/src/subscription-stripe/changes.json +6 -0
  47. package/packages/bundled-features/src/subscription-stripe/feature.ts +9 -0
  48. package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts +7 -1
  49. package/samples/apps/use-all-bundled/feature-manifest.json +63 -1
  50. package/samples/apps/use-all-bundled/kumiko/migrations/0068_signature.rebuild.json +4 -0
  51. package/samples/apps/use-all-bundled/src/run-config.ts +35 -1
  52. package/samples/recipes/embedded/README.md +4 -0
  53. package/samples/recipes/embedded/src/entities/invoice.ts +6 -0
  54. package/samples/recipes/embedded/src/feature.ts +7 -1
  55. package/samples/recipes/embedded/src/handlers/invoice-receive.write.ts +1 -0
  56. package/samples/recipes/embedded/src/screens/invoice-receive.screen.ts +2 -0
  57. package/samples/recipes/handbook-knowledge/README.md +22 -0
  58. package/samples/recipes/handbook-knowledge/package.json +12 -0
  59. package/samples/recipes/handbook-knowledge/src/feature.ts +42 -0
  60. package/samples/recipes/signature/README.md +21 -0
  61. package/samples/recipes/signature/package.json +13 -0
  62. package/samples/recipes/signature/src/feature.ts +26 -0
@@ -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
- { paymentInvoiceCreation = true }: StripeCheckoutSessionRuntimeOptions = {},
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": 94,
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.",
@@ -0,0 +1,4 @@
1
+ {
2
+ "version": 1,
3
+ "tables": ["read_signature_requests", "read_signature_signers"]
4
+ }
@@ -55,6 +55,7 @@ import { createFoldersFeature } from "@cosmicdrift/kumiko-bundled-features/folde
55
55
  import { createFoldersUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/folders-user-data";
56
56
  import { createFormDraftFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft";
57
57
  import { createFormDraftUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft-user-data";
58
+ import { createHandbookKnowledgeFeature } from "@cosmicdrift/kumiko-bundled-features/handbook-knowledge";
58
59
  import {
59
60
  createHelpdeskFeature,
60
61
  helpdeskOpenRequestsPanels,
@@ -81,6 +82,7 @@ import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-fea
81
82
  import { createRendererPdfFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
82
83
  import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
83
84
  import { createSeoFeature } from "@cosmicdrift/kumiko-bundled-features/seo";
85
+ import { createSignatureFeature } from "@cosmicdrift/kumiko-bundled-features/signature";
84
86
  import { createStepDispatcherFeature } from "@cosmicdrift/kumiko-bundled-features/step-dispatcher";
85
87
  import { createSubscriptionMollieFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-mollie";
86
88
  import { createSubscriptionPaddleFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-paddle";
@@ -106,7 +108,10 @@ import {
106
108
  import { createDocumentDesignerFeature } from "@cosmicdrift/kumiko-document-designer";
107
109
  import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
108
110
  import { localeDe } from "@cosmicdrift/kumiko-locale-de";
109
- import { createRendererPuppeteerClientFeature } from "@cosmicdrift/kumiko-renderer-puppeteer-client";
111
+ import {
112
+ createRendererPuppeteerClientFeature,
113
+ renderHtmlToPdf,
114
+ } from "@cosmicdrift/kumiko-renderer-puppeteer-client";
110
115
  import { ADMIN_NAV_QN, ADMIN_NAV_WORKSPACES, adminNavFeature } from "./app/admin-nav-feature";
111
116
  import { DEV_TENANT_ID } from "./app/auth-constants";
112
117
  import { CAP_OVERVIEW_CAPS } from "./app/cap-overview-caps";
@@ -374,6 +379,35 @@ export const APP_FEATURES = [
374
379
  // PDF printing for document templates; the print service is reached through
375
380
  // PUPPETEER_SERVICE_URL + PUPPETEER_AUTH_TOKEN and only asked when a PDF is generated.
376
381
  createRendererPuppeteerClientFeature(),
382
+ // signature: needs files; the print function is the real client, asked only when a request completes.
383
+ // deliverLink is smoke-only: boot never sends a link.
384
+ createSignatureFeature({
385
+ retention: { keepFor: "10y" },
386
+ renderHtmlToPdf,
387
+ linkSecret: SMOKE_HMAC_SECRET,
388
+ signaturePageUrl: "https://use-all-bundled.example/sign",
389
+ deliverLink: async () => {
390
+ /* smoke-only */
391
+ },
392
+ }),
393
+ createHandbookKnowledgeFeature({
394
+ pages: {
395
+ defaultLocale: "en",
396
+ locales: {
397
+ en: [
398
+ {
399
+ id: "sign-a-document",
400
+ kind: "process",
401
+ title: "Sign a document",
402
+ questions: ["How do I get a document signed?"],
403
+ screens: [],
404
+ bodyMd: "Create a signature request, add the signers and send each a link.",
405
+ },
406
+ ],
407
+ },
408
+ },
409
+ access: { roles: ["TenantAdmin", "TenantMember", "SystemAdmin"] },
410
+ }),
377
411
 
378
412
  // managed-pages: requires config (auto-bundled). Every host resolves to the
379
413
  // dev tenant so the document-editor e2e can read a saved page back from the
@@ -26,6 +26,10 @@ object and an embedded list rendered by a declarative `entityEdit` screen.
26
26
  entries (`{ label, from }`). The handler wraps its schema with
27
27
  `withFormDerivations(schema, screen)` (`src/handlers/invoice-receive.write.ts`),
28
28
  so totals sent by the client are replaced on the server.
29
+ - **Redirect with search params**: after submit, `invoice-receive` redirects to
30
+ `invoice-list` with `searchParams: { "invoice-list.q": "invoiceNumber" }`, so the list opens
31
+ with the number the handler returns in its search box. The receive handler stores nothing in
32
+ this recipe; the search finds invoices saved through `invoice-edit` with that number.
29
33
 
30
34
  ## When to reach for it
31
35
 
@@ -13,6 +13,12 @@ export const invoiceEntity = createEntity({
13
13
  table: "read_sample_invoices",
14
14
  fields: {
15
15
  customer: createTextField({ personal: { of: "id" }, find: "none", required: true }),
16
+ // Business data, so the list can search it: invoice-receive redirects here by number.
17
+ invoiceNumber: createTextField({
18
+ personal: false,
19
+ reason: "is_business_data",
20
+ searchable: true,
21
+ }),
16
22
  lines: createEmbeddedListField(
17
23
  {
18
24
  product: { type: "reference", entity: "product", required: true },
@@ -58,9 +58,15 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
58
58
  type: "entityEdit",
59
59
  entity: "invoice",
60
60
  layout: {
61
- sections: [{ columns: 1, fields: ["customer", "lines"] }],
61
+ sections: [{ columns: 1, fields: ["invoiceNumber", "customer", "lines"] }],
62
62
  },
63
63
  });
64
64
 
65
+ r.screen({
66
+ id: "invoice-list",
67
+ type: "entityList",
68
+ entity: "invoice",
69
+ columns: ["invoiceNumber", "customer"],
70
+ });
65
71
  r.screen(invoiceReceiveScreen);
66
72
  });
@@ -29,6 +29,7 @@ export const invoiceReceive = defineWriteHandler({
29
29
  handler: async (event) => ({
30
30
  isSuccess: true,
31
31
  data: {
32
+ invoiceNumber: event.payload.invoiceNumber,
32
33
  netTotal: event.payload.netTotal,
33
34
  vatTotal: event.payload.vatTotal,
34
35
  grossTotal: event.payload.grossTotal,
@@ -30,6 +30,8 @@ export const invoiceReceiveScreen: ActionFormScreenDefinition = {
30
30
  id: "invoice-receive",
31
31
  type: "actionForm",
32
32
  handler: "contacts:write:invoice:receive",
33
+ // Lands on the invoice list with its search box filled from the result.
34
+ redirect: { screen: "invoice-list", searchParams: { "invoice-list.q": "invoiceNumber" } },
33
35
  fields: {
34
36
  supplier: createTextField({ required: true, personal: "tenant", find: "none" }),
35
37
  invoiceNumber: createTextField({
@@ -0,0 +1,22 @@
1
+ # Handbook knowledge
2
+
3
+ Serves the app's handbook to the AI assistant. `kumiko handbuch knowledge` exports
4
+ the pages per locale as JSON; the `handbook-knowledge` bundled feature mounts them
5
+ as two query tools, so the assistant can answer how-do-I questions from the real
6
+ handbook text.
7
+
8
+ ## What it shows
9
+
10
+ - **Feature** — `createHandbookKnowledgeFeature({ pages, access, publicPath })`.
11
+ No entity, no migration; `access` decides which roles see the tools.
12
+ - **list-pages** — catalog of id, kind, title and questions in the caller's language.
13
+ - **read-page** — one page body; the language falls back to the handbook's default
14
+ language, long pages are cut with a visible notice, unknown ids are `not_found`.
15
+ - **Test** — `setupTestStack` and HTTP with an `X-Locale` header.
16
+
17
+ ## Files
18
+
19
+ ```
20
+ src/feature.ts fixed handbook JSON and the feature
21
+ src/__tests__/feature.integration.test.ts list-pages, read-page, fallback, not found
22
+ ```
@@ -0,0 +1,12 @@
1
+ {
2
+ "name": "@cosmicdrift/kumiko-sample-handbook-knowledge",
3
+ "description": "The handbook-knowledge bundled feature: a fixed handbook JSON served to the AI assistant as list-pages and read-page query tools.",
4
+ "private": true,
5
+ "dependencies": {
6
+ "@cosmicdrift/kumiko-bundled-features": "workspace:*",
7
+ "@cosmicdrift/kumiko-framework": "workspace:*"
8
+ },
9
+ "devDependencies": {
10
+ "@cosmicdrift/kumiko-testing": "workspace:*"
11
+ }
12
+ }
@@ -0,0 +1,42 @@
1
+ import { createHandbookKnowledgeFeature } from "@cosmicdrift/kumiko-bundled-features/handbook-knowledge";
2
+
3
+ // In an app this object is the output of `kumiko handbuch knowledge <config> --out <file>`.
4
+ const handbook = {
5
+ defaultLocale: "en",
6
+ locales: {
7
+ en: [
8
+ {
9
+ id: "prozess-add-tenant",
10
+ kind: "process" as const,
11
+ title: "Add a tenant",
12
+ questions: ["How do I add a tenant?"],
13
+ screens: [],
14
+ bodyMd: "Open the lease, choose Add tenant and confirm the change.",
15
+ },
16
+ {
17
+ id: "lease-detail",
18
+ kind: "screen" as const,
19
+ title: "Lease",
20
+ questions: [],
21
+ screens: [],
22
+ bodyMd: "The lease screen shows tenants, rent and documents.",
23
+ },
24
+ ],
25
+ de: [
26
+ {
27
+ id: "prozess-add-tenant",
28
+ kind: "process" as const,
29
+ title: "Mieter hinzufügen",
30
+ questions: ["Wie füge ich einen Mieter hinzu?"],
31
+ screens: [],
32
+ bodyMd: "Vertrag öffnen, Mieter hinzufügen wählen und die Änderung bestätigen.",
33
+ },
34
+ ],
35
+ },
36
+ };
37
+
38
+ export const handbookKnowledgeFeature = createHandbookKnowledgeFeature({
39
+ pages: handbook,
40
+ access: { roles: ["User"] },
41
+ publicPath: "/handbuch",
42
+ });
@@ -0,0 +1,21 @@
1
+ # Signature
2
+
3
+ Several people sign one PDF of the tenant, in person on a display or through a link. The last
4
+ signature moves the request to `all-signed`; a job renders a signature page, appends it to the
5
+ unchanged original and completes the request.
6
+
7
+ ## What it shows
8
+
9
+ - **Feature** - `createSignatureFeature({ retention, linkSecret, renderHtmlToPdf, deliverLink, signaturePageUrl })`.
10
+ Needs `files` and `user-data-rights` (exports and erases signer data); the test mounts user-data-rights with its own dependencies.
11
+ - **deliverLink** - `issue-link` hands the signing link to the app (mail) and returns only
12
+ `{ signerId, linkSentAt }`: whoever may issue a link must not be able to sign with it.
13
+ - **renderHtmlToPdf** - injected; in an app it is the client of `@cosmicdrift/kumiko-renderer-puppeteer-client`.
14
+ - **Test** - `setupTestStack` and HTTP: request, issue-link, anonymous sign-by-link, sweep job, completed.
15
+
16
+ ## Files
17
+
18
+ ```
19
+ src/feature.ts the feature with a link outbox and a stand-in printer
20
+ src/__tests__/feature.integration.test.ts request to completed request over HTTP
21
+ ```
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "@cosmicdrift/kumiko-sample-signature",
3
+ "description": "The signature bundled feature: a request for several signers, a signing link that is delivered by the app, and a completed PDF with a signature page.",
4
+ "private": true,
5
+ "dependencies": {
6
+ "@cosmicdrift/kumiko-bundled-features": "workspace:*",
7
+ "@cosmicdrift/kumiko-framework": "workspace:*",
8
+ "pdf-lib": "^1.17.1"
9
+ },
10
+ "devDependencies": {
11
+ "@cosmicdrift/kumiko-testing": "workspace:*"
12
+ }
13
+ }
@@ -0,0 +1,26 @@
1
+ import { createSignatureFeature } from "@cosmicdrift/kumiko-bundled-features/signature";
2
+ import { PDFDocument } from "pdf-lib";
3
+
4
+ // In an app `deliverLink` sends a mail to the signer. The recipe keeps the links in a map so the
5
+ // test can open them: the link is never part of a handler result.
6
+ export const deliveredLinks = new Map<string, string>();
7
+
8
+ // In an app this is `renderHtmlToPdf` from @cosmicdrift/kumiko-renderer-puppeteer-client, which
9
+ // needs the print service; the recipe prints a blank page instead.
10
+ async function printSignaturePage(): Promise<Uint8Array> {
11
+ const pdf = await PDFDocument.create();
12
+ pdf.addPage();
13
+ return pdf.save();
14
+ }
15
+
16
+ export const SIGNATURE_LINK_SECRET = "signature-recipe-link-secret-0123456789";
17
+
18
+ export const signatureFeature = createSignatureFeature({
19
+ retention: { keepFor: "10y" },
20
+ linkSecret: SIGNATURE_LINK_SECRET,
21
+ renderHtmlToPdf: printSignaturePage,
22
+ signaturePageUrl: "https://app.example/sign",
23
+ deliverLink: async (_ctx, { signerId, url }) => {
24
+ deliveredLinks.set(signerId, url);
25
+ },
26
+ });