@cosmicdrift/kumiko-framework 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.
Files changed (90) hide show
  1. package/agents/api/framework-engine.md +67 -13
  2. package/agents/api/framework-ui-types.md +81 -7
  3. package/agents/api/renderer-web.md +31 -3
  4. package/agents/api/types.md +114 -61
  5. package/agents/api.md +1 -1
  6. package/agents/boot-rules.md +36 -4
  7. package/agents/examples/dashboard-stats.md +51 -0
  8. package/agents/examples/embedded.md +24 -1
  9. package/agents/examples/event-sourcing.md +84 -0
  10. package/agents/examples/handbook-knowledge.md +129 -0
  11. package/agents/examples/list-table-options.md +71 -5
  12. package/agents/examples/managed-config.md +9 -1
  13. package/agents/examples/record-detail-layout.md +71 -6
  14. package/agents/examples/secrets-demo.md +3 -1
  15. package/agents/examples/signature.md +187 -0
  16. package/agents/examples/writeform-section.md +330 -0
  17. package/agents/examples.md +2 -0
  18. package/agents/features-index.md +4 -0
  19. package/agents/features.md +14 -0
  20. package/dist/api/server-routes.js +2 -0
  21. package/dist/db/queries/event-store.d.ts +3 -0
  22. package/dist/db/queries/event-store.js +12 -0
  23. package/dist/db/table-builder.js +3 -1
  24. package/dist/engine/boot-validator/boot-phases.js +5 -0
  25. package/dist/engine/boot-validator/boot-rules.d.ts +140 -5
  26. package/dist/engine/boot-validator/card-meta-overflow.js +5 -1
  27. package/dist/engine/boot-validator/cross-tenant-file-read.d.ts +3 -0
  28. package/dist/engine/boot-validator/cross-tenant-file-read.js +19 -0
  29. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +10 -0
  30. package/dist/engine/boot-validator/entity-declaration-rules.js +10 -0
  31. package/dist/engine/boot-validator/list-row-guidance-rules.d.ts +16 -1
  32. package/dist/engine/boot-validator/list-row-guidance-rules.js +16 -1
  33. package/dist/engine/boot-validator/list-row-guidance.d.ts +8 -0
  34. package/dist/engine/boot-validator/list-row-guidance.js +31 -0
  35. package/dist/engine/boot-validator/list-table-options.d.ts +1 -1
  36. package/dist/engine/boot-validator/list-table-options.js +8 -6
  37. package/dist/engine/boot-validator/list-table-rules.d.ts +1 -1
  38. package/dist/engine/boot-validator/list-table-rules.js +1 -1
  39. package/dist/engine/boot-validator/query-output-columns.js +22 -0
  40. package/dist/engine/boot-validator/query-output-guidance.js +3 -0
  41. package/dist/engine/boot-validator/query-refs.js +4 -1
  42. package/dist/engine/boot-validator/relative-time-format.d.ts +1 -0
  43. package/dist/engine/boot-validator/relative-time-format.js +51 -0
  44. package/dist/engine/boot-validator/screens-actions-rules.d.ts +16 -1
  45. package/dist/engine/boot-validator/screens-actions-rules.js +16 -1
  46. package/dist/engine/boot-validator/screens-actions.d.ts +1 -1
  47. package/dist/engine/boot-validator/screens-actions.js +57 -15
  48. package/dist/engine/boot-validator/screens-dashboard-narrow.d.ts +2 -1
  49. package/dist/engine/boot-validator/screens-dashboard-narrow.js +43 -4
  50. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +12 -2
  51. package/dist/engine/boot-validator/screens-dashboard-rules.js +12 -2
  52. package/dist/engine/boot-validator/screens-dashboard.js +2 -1
  53. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +5 -0
  54. package/dist/engine/boot-validator/screens-forms-layout-rules.js +5 -0
  55. package/dist/engine/boot-validator/screens-forms-rules.d.ts +60 -0
  56. package/dist/engine/boot-validator/screens-forms-rules.js +60 -0
  57. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  58. package/dist/engine/boot-validator/screens-forms.js +108 -2
  59. package/dist/engine/boot-validator/screens-kind-config-edit.js +1 -0
  60. package/dist/engine/boot-validator/screens-kind-entity-list.js +3 -1
  61. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +15 -0
  62. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +15 -0
  63. package/dist/engine/boot-validator/screens-kind-projection-detail.js +110 -0
  64. package/dist/engine/boot-validator/screens-kind-projection-list.js +1 -1
  65. package/dist/engine/boot-validator/screens-lists-rules.d.ts +5 -0
  66. package/dist/engine/boot-validator/screens-lists-rules.js +5 -0
  67. package/dist/engine/boot-validator/screens-lists.js +4 -1
  68. package/dist/engine/boot-validator/screens.js +1 -2
  69. package/dist/engine/bridge-stub.js +1 -0
  70. package/dist/engine/build-config-feature-schema.js +29 -36
  71. package/dist/engine/config-access-rules.d.ts +3 -0
  72. package/dist/engine/config-access-rules.js +34 -0
  73. package/dist/engine/factories.d.ts +2 -0
  74. package/dist/engine/project-app-schema-for-roles.js +2 -0
  75. package/dist/engine/screen-helpers.js +7 -3
  76. package/dist/event-store/archive.d.ts +1 -0
  77. package/dist/event-store/archive.js +5 -1
  78. package/dist/event-store/event-store.d.ts +5 -0
  79. package/dist/event-store/event-store.js +23 -3
  80. package/dist/files/file-routes.d.ts +2 -0
  81. package/dist/files/file-routes.js +85 -22
  82. package/dist/files/foreign-tenant-file-read.d.ts +13 -0
  83. package/dist/files/foreign-tenant-file-read.js +64 -0
  84. package/dist/i18n/required-surface-keys.js +32 -6
  85. package/dist/pipeline/handler-context-events.js +15 -1
  86. package/dist/ui-types/card-column-roles.d.ts +3 -0
  87. package/dist/ui-types/card-column-roles.js +9 -5
  88. package/dist/ui-types/index.d.ts +1 -1
  89. package/package.json +3 -3
  90. package/src/changes.json +48 -0
@@ -51,6 +51,13 @@ header, a metrics band, and a tabbed layout instead of one long stacked form.
51
51
  - round 6 (board gaps): `rowLink.screenField` / `paramsField` (target screen from a query field),
52
52
  list panel `icon`, `narrow.moreText`, `narrow.field` as any query output field,
53
53
  `footerLink.narrowOnly`, `narrow.titleField` on cards and `rowToneMarker: "dot"`
54
+ - round 7 (board look): `header.narrowTitle` (short phone top-bar title), banner `iconless`,
55
+ `metricsPlacement: { narrow: "before-steps" }`, `mobileSummary` (one line instead of the
56
+ metrics below `sm`), `MetricSpec.visibleWhen`, field option `concealed` (muted value with a lock),
57
+ section `hideOnNarrow` and `after` (a registered component under the items tab card), and a
58
+ second screen `order-facts` with a stacked layout and `pageNavigation: false`
59
+ - not shown: `photosBeside` (needs a stored image file for `photoGrid`) and `recordSections.omitFirstTitle`
60
+ (a renderer prop, not reachable from a screen declaration)
54
61
  - boot-validator catching two common author mistakes: a `metrics` entry
55
62
  with an empty `label`, and a `tabs` layout with fewer than two
56
63
  sections
@@ -334,6 +341,10 @@ function OrderInternalNote(): ReactNode {
334
341
  );
335
342
  }
336
343
 
344
+ function OrderItemsFooter(): ReactNode {
345
+ return <p data-testid="order-items-footer">Prices include VAT.</p>;
346
+ }
347
+
337
348
  function OrderInboxIcon(): ReactNode {
338
349
  return (
339
350
  <svg aria-hidden="true" width="16" height="16" viewBox="0 0 16 16" fill="none">
@@ -372,7 +383,9 @@ function Shell({
372
383
  schema={schema}
373
384
  user={{ id: "u1", roles: ["Admin"] }}
374
385
  >
375
- <ExtensionSectionsProvider value={{ OrderInboxIcon, DeadlinesIcon, OrderInternalNote }}>
386
+ <ExtensionSectionsProvider
387
+ value={{ OrderInboxIcon, DeadlinesIcon, OrderInternalNote, OrderItemsFooter }}
388
+ >
376
389
  {isPinnedRecord && feature !== undefined ? (
377
390
  <KumikoScreen schema={feature} qn={ORDER_DETAIL_SCREEN_QN} entityId="order-1" />
378
391
  ) : (
@@ -471,6 +484,7 @@ function orderDetailForUrl(id: string): Record<string, unknown> {
471
484
  summaryLine,
472
485
  summaryShort,
473
486
  summaryTone,
487
+ mobileLine,
474
488
  notice,
475
489
  steps,
476
490
  progress,
@@ -478,7 +492,17 @@ function orderDetailForUrl(id: string): Record<string, unknown> {
478
492
  } = answerOrderDetail(id);
479
493
  const withGuidance = new URLSearchParams(window.location.search).has("guidance");
480
494
  return withGuidance
481
- ? { ...withoutGuidance, path, summaryLine, summaryShort, summaryTone, notice, steps, progress }
495
+ ? {
496
+ ...withoutGuidance,
497
+ path,
498
+ summaryLine,
499
+ summaryShort,
500
+ summaryTone,
501
+ mobileLine,
502
+ notice,
503
+ steps,
504
+ progress,
505
+ }
482
506
  : withoutGuidance;
483
507
  }
484
508
 
@@ -632,7 +656,8 @@ test.describe("record-detail-layout — tab-panel height", () => {
632
656
  expect(region.y + region.height).toBeLessThanOrEqual(main.y + main.height + 4);
633
657
  expect(table.height).toBeLessThan(region.height);
634
658
  expect(table.height).toBeLessThan(main.height * 0.4);
635
- await expect(page.getByTestId("render-list-table-footer")).toBeVisible();
659
+ // A tab's table has no count footer: the tab label already says how many rows there are.
660
+ await expect(page.getByTestId("render-list-table-footer")).toHaveCount(0);
636
661
  });
637
662
 
638
663
  test("long list: the tab-panel card is capped at the panel's available height and the table scrolls internally", async ({
@@ -1049,6 +1074,7 @@ describe("record-detail-layout showcase — registration", () => {
1049
1074
  expect(screen.header).toEqual({
1050
1075
  title: "customerName",
1051
1076
  shortTitle: "shortTitle",
1077
+ narrowTitle: "order-desk.header.narrow-title",
1052
1078
  narrowSubtitle: "narrowSubtitle",
1053
1079
  subtitle: [
1054
1080
  "orderNumber",
@@ -1225,7 +1251,7 @@ describe("record-detail-layout showcase — board gaps", () => {
1225
1251
  const detail = registry.getScreen("order-desk:screen:order-detail");
1226
1252
  if (detail?.type !== "projectionDetail") throw new Error("expected projectionDetail");
1227
1253
  expect(detail.progress?.placement).toBe("beside-steps");
1228
- expect(detail.metricsPlacement).toEqual({ narrow: "after-guidance" });
1254
+ expect(detail.metricsPlacement).toEqual({ narrow: "before-steps" });
1229
1255
  expect(detail.metrics?.map((metric) => metric.subField)).toContain("totalNote");
1230
1256
  });
1231
1257
  });
@@ -1657,6 +1683,10 @@ export function createOrderDeskFeature(): FeatureDefinition {
1657
1683
  "order-desk.metric.outstandingAmount": { en: "Outstanding" },
1658
1684
  "order-desk.metric.itemCount": { en: "Items" },
1659
1685
  "order-desk.metric.placedAt": { en: "Placed" },
1686
+ "order-desk.header.narrow-title": { en: "Order" },
1687
+ "screen:order-facts.title": { en: "Order facts" },
1688
+ "order-desk.facts.contact": { en: "Contact" },
1689
+ "order-desk.facts.address": { en: "Address" },
1660
1690
  "order-desk.tab.items": { en: "Items" },
1661
1691
  "order-desk.tab.payments": { en: "Payments" },
1662
1692
  "order-desk.tab.details": { en: "Details" },
@@ -1709,6 +1739,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
1709
1739
  },
1710
1740
  ],
1711
1741
  defaultSort: { field: "urgency", dir: "desc" },
1742
+ toolbarSort: true,
1712
1743
  sortOptions: [
1713
1744
  { field: "urgency", dir: "desc", label: "order-desk.sort.urgency" },
1714
1745
  { field: "customerName", dir: "asc", label: "order-desk.sort.customer" },
@@ -1950,6 +1981,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
1950
1981
  header: {
1951
1982
  title: "customerName",
1952
1983
  shortTitle: "shortTitle",
1984
+ narrowTitle: "order-desk.header.narrow-title",
1953
1985
  // Parts are joined by a separator; `format` formats the raw field value.
1954
1986
  narrowSubtitle: "narrowSubtitle",
1955
1987
  subtitle: [
@@ -1962,6 +1994,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
1962
1994
  summary: { field: "summaryLine", narrowField: "summaryShort", toneField: "summaryTone" },
1963
1995
  banner: {
1964
1996
  field: "notice",
1997
+ iconless: true,
1965
1998
  actions: [
1966
1999
  {
1967
2000
  kind: "navigate",
@@ -1999,8 +2032,9 @@ export function createOrderDeskFeature(): FeatureDefinition {
1999
2032
  },
2000
2033
  ],
2001
2034
  },
2035
+ mobileSummary: "mobileLine",
2002
2036
  metricsStyle: "tiles",
2003
- metricsPlacement: { narrow: "after-guidance" },
2037
+ metricsPlacement: { narrow: "before-steps" },
2004
2038
  metrics: [
2005
2039
  {
2006
2040
  field: "totalAmount",
@@ -2014,6 +2048,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
2014
2048
  subField: "outstandingNote",
2015
2049
  tone: "warn",
2016
2050
  toneField: "outstandingTone",
2051
+ visibleWhen: { field: "status", ne: "delivered" },
2017
2052
  navigate: { tab: "payments" },
2018
2053
  },
2019
2054
  {
@@ -2031,6 +2066,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
2031
2066
  kind: "relatedList",
2032
2067
  title: "order-desk.tab.items",
2033
2068
  countField: "itemsCount",
2069
+ after: { react: { __component: "OrderItemsFooter" } },
2034
2070
  query: "order-desk:query:order:items",
2035
2071
  columns: [
2036
2072
  { field: "sku", label: "order-desk.col.sku" },
@@ -2073,11 +2109,12 @@ export function createOrderDeskFeature(): FeatureDefinition {
2073
2109
  id: "details",
2074
2110
  kind: "fields",
2075
2111
  title: "order-desk.tab.details",
2076
- fields: ["shippingAddress", "billingAddress", "salesRep"],
2112
+ fields: ["shippingAddress", { field: "billingAddress", concealed: true }, "salesRep"],
2077
2113
  },
2078
2114
  {
2079
2115
  id: "internal-note",
2080
2116
  kind: "extension",
2117
+ hideOnNarrow: true,
2081
2118
  title: "order-desk.tab.internalNote",
2082
2119
  component: { react: { __component: "OrderInternalNote" } },
2083
2120
  entityName: "order",
@@ -2111,6 +2148,33 @@ export function createOrderDeskFeature(): FeatureDefinition {
2111
2148
  inlineActions: ["download-invoice"],
2112
2149
  access: accessRoles,
2113
2150
  });
2151
+
2152
+ r.screen({
2153
+ id: "order-facts",
2154
+ type: "projectionDetail",
2155
+ query: "order-desk:query:order:detail",
2156
+ listScreenId: "orders",
2157
+ header: { title: "customerName" },
2158
+ // Two short stacked sections need no "On this page" index.
2159
+ pageNavigation: false,
2160
+ layout: {
2161
+ sections: [
2162
+ {
2163
+ id: "contact",
2164
+ kind: "fields",
2165
+ title: "order-desk.facts.contact",
2166
+ fields: ["salesRep"],
2167
+ },
2168
+ {
2169
+ id: "address",
2170
+ kind: "fields",
2171
+ title: "order-desk.facts.address",
2172
+ fields: ["shippingAddress", "billingAddress"],
2173
+ },
2174
+ ],
2175
+ },
2176
+ access: accessRoles,
2177
+ });
2114
2178
  });
2115
2179
  }
2116
2180
  ```
@@ -2614,6 +2678,7 @@ export function answerOrderDetail(id: string) {
2614
2678
  path: [{ label: "Orders" }, { label: "Aiko Tanaka" }, { label: "SO-10482" }],
2615
2679
  summaryLine: "Waiting for the second payment",
2616
2680
  summaryShort: "Second payment open.",
2681
+ mobileLine: "€ 312.00 open of € 1,248.00",
2617
2682
  summaryTone: "warn",
2618
2683
  narrowSubtitle: "SO-10482 · placed 21 Aug",
2619
2684
  notice: { title: "Payment overdue", text: "312 EUR is 14 days overdue", tone: "bad" },
@@ -14,7 +14,7 @@ Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation.
14
14
 
15
15
  - `r.secret` + `ctx.services.secrets.get` (audited reads)
16
16
  - Charge-style handler that never returns the plaintext key
17
- - A system-scope secret edited on a `configEdit` screen (`secretKeys`) with a handler button row (`actions`)
17
+ - A system-scope secret edited on a `configEdit` screen (`secretKeys`) with a handler button row (`actions`) and `compact: true` (no origin icon, reset link or accent bar)
18
18
 
19
19
  ## Source
20
20
 
@@ -498,6 +498,8 @@ export function createBillingFeature(): FeatureDefinition {
498
498
  }),
499
499
  },
500
500
  layout: { variant: "settings-list", sections: [{ fields: ["signingKey"] }] },
501
+ // One write-only field needs no origin icon, reset link or accent bar.
502
+ compact: true,
501
503
  // A button row calls a handler with {} on the stored values; it is disabled while the
502
504
  // form has unsaved changes.
503
505
  actions: [
@@ -0,0 +1,187 @@
1
+ <!-- Generated by `bun run gen:agent-docs` from samples/recipes/signature. Do not edit. -->
2
+
3
+ # signature
4
+
5
+ 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.
6
+
7
+ ## README
8
+
9
+ # Signature
10
+
11
+ Several people sign one PDF of the tenant, in person on a display or through a link. The last
12
+ signature moves the request to `all-signed`; a job renders a signature page, appends it to the
13
+ unchanged original and completes the request.
14
+
15
+ ## What it shows
16
+
17
+ - **Feature** - `createSignatureFeature({ retention, linkSecret, renderHtmlToPdf, deliverLink, signaturePageUrl })`.
18
+ Needs `files` and `user-data-rights` (exports and erases signer data); the test mounts user-data-rights with its own dependencies.
19
+ - **deliverLink** - `issue-link` hands the signing link to the app (mail) and returns only
20
+ `{ signerId, linkSentAt }`: whoever may issue a link must not be able to sign with it.
21
+ - **renderHtmlToPdf** - injected; in an app it is the client of `@cosmicdrift/kumiko-renderer-puppeteer-client`.
22
+ - **Test** - `setupTestStack` and HTTP: request, issue-link, anonymous sign-by-link, sweep job, completed.
23
+
24
+ ## Files
25
+
26
+ ```
27
+ src/feature.ts the feature with a link outbox and a stand-in printer
28
+ src/__tests__/feature.integration.test.ts request to completed request over HTTP
29
+ ```
30
+
31
+ ## Source files
32
+
33
+ ### src/__tests__/feature.integration.test.ts
34
+
35
+ ```ts
36
+ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
37
+ import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
38
+ import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
39
+ import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
40
+ import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
41
+ import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
42
+ import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
43
+ import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
44
+ import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
45
+ import {
46
+ createFilesFeature,
47
+ createInMemoryFileProvider,
48
+ fileRefEntity,
49
+ fileRefsTable,
50
+ } from "@cosmicdrift/kumiko-framework/files";
51
+ import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
52
+ import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
53
+ import { PDFDocument } from "pdf-lib";
54
+ import { deliveredLinks, signatureFeature } from "../feature";
55
+
56
+ const TENANT = testTenantId(1);
57
+ const admin = createTestUser({ roles: ["TenantAdmin"], tenantId: TENANT });
58
+ const SIGNATURE_PNG =
59
+ "iVBORw0KGgoAAAANSUhEUgAAACgAAAAQCAYAAABk1z2tAAAANklEQVR4nGNgYGD4j4QHJUB24KB0LC4HDjqHgsCoY0dDdTS9jmas0SJrtGwdrbVGq9f/yCUBAOaodYsn7bfwAAAAAElFTkSuQmCC";
60
+
61
+ const provider = createInMemoryFileProvider();
62
+ let stack: TestStack;
63
+
64
+ beforeAll(async () => {
65
+ stack = await setupTestStack({
66
+ features: [
67
+ createUserFeature(),
68
+ createAuthFoundationFeature(),
69
+ createSessionsFeature(),
70
+ createDataRetentionFeature(),
71
+ createComplianceProfilesFeature(),
72
+ createUserDataRightsFeature(),
73
+ createFilesFeature(),
74
+ signatureFeature,
75
+ ],
76
+ files: { storageProvider: provider },
77
+ jobs: { consumerLane: "worker", getActiveTenantIds: async () => [TENANT] },
78
+ anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
79
+ });
80
+ });
81
+
82
+ afterAll(async () => {
83
+ await stack.cleanup();
84
+ });
85
+
86
+ // The requester uploads the contract: a request needs a document its caller may open.
87
+ async function seedContract(): Promise<string> {
88
+ const bytes = await (async () => {
89
+ const pdf = await PDFDocument.create();
90
+ pdf.addPage();
91
+ return pdf.save();
92
+ })();
93
+ const storageKey = `${TENANT}/contract.pdf`;
94
+ await provider.write(storageKey, bytes, "application/pdf");
95
+ const db = createTenantDb({
96
+ db: stack.db,
97
+ tenantId: TENANT,
98
+ mode: "system",
99
+ reason: "recipe seeds the document the request refers to",
100
+ });
101
+ const created = await createEventStoreExecutor(fileRefsTable, fileRefEntity, {
102
+ entityName: "fileRef",
103
+ }).create(
104
+ { storageKey, fileName: "contract.pdf", mimeType: "application/pdf", size: bytes.length },
105
+ admin,
106
+ db,
107
+ );
108
+ if (!created.isSuccess) throw new Error(created.error.message);
109
+ return String(created.data.id);
110
+ }
111
+
112
+ describe("signature recipe", () => {
113
+ test("a link is delivered, never returned, and the last signature completes the request", async () => {
114
+ const { requestId, signerIds } = await stack.http.writeOk<{
115
+ requestId: string;
116
+ signerIds: string[];
117
+ }>(
118
+ "signature:write:request",
119
+ {
120
+ documentFileId: await seedContract(),
121
+ title: "Rental agreement",
122
+ subjectType: "lease",
123
+ subjectId: "lease-1",
124
+ signers: [{ name: "Ada", email: "ada@example.test" }],
125
+ },
126
+ admin,
127
+ );
128
+ const signerId = signerIds[0] as string;
129
+
130
+ const issued = await stack.http.writeOk<Record<string, unknown>>(
131
+ "signature:write:issue-link",
132
+ { signerId },
133
+ admin,
134
+ );
135
+ expect(Object.keys(issued).sort()).toEqual(["linkSentAt", "signerId"]);
136
+
137
+ const url = deliveredLinks.get(signerId) ?? "";
138
+ expect(url.startsWith("https://app.example/sign#")).toBe(true);
139
+ const signed = await stack.http.raw("POST", "/api/write", {
140
+ type: "signature:write:sign-by-link",
141
+ payload: { token: url.slice(url.indexOf("#") + 1), imagePngBase64: SIGNATURE_PNG },
142
+ });
143
+ expect(signed.status).toBe(200);
144
+
145
+ await stack.jobRunner?.dispatch("signature:job:sweep", { tenantId: TENANT });
146
+ await stack.drainJobs();
147
+
148
+ const request = await stack.http.queryOk<{ status: string }>(
149
+ "signature:query:signature-request:detail",
150
+ { id: requestId },
151
+ admin,
152
+ );
153
+ expect(request.status).toBe("completed");
154
+ });
155
+ });
156
+ ```
157
+
158
+ ### src/feature.ts
159
+
160
+ ```ts
161
+ import { createSignatureFeature } from "@cosmicdrift/kumiko-bundled-features/signature";
162
+ import { PDFDocument } from "pdf-lib";
163
+
164
+ // In an app `deliverLink` sends a mail to the signer. The recipe keeps the links in a map so the
165
+ // test can open them: the link is never part of a handler result.
166
+ export const deliveredLinks = new Map<string, string>();
167
+
168
+ // In an app this is `renderHtmlToPdf` from @cosmicdrift/kumiko-renderer-puppeteer-client, which
169
+ // needs the print service; the recipe prints a blank page instead.
170
+ async function printSignaturePage(): Promise<Uint8Array> {
171
+ const pdf = await PDFDocument.create();
172
+ pdf.addPage();
173
+ return pdf.save();
174
+ }
175
+
176
+ export const SIGNATURE_LINK_SECRET = "signature-recipe-link-secret-0123456789";
177
+
178
+ export const signatureFeature = createSignatureFeature({
179
+ retention: { keepFor: "10y" },
180
+ linkSecret: SIGNATURE_LINK_SECRET,
181
+ renderHtmlToPdf: printSignaturePage,
182
+ signaturePageUrl: "https://app.example/sign",
183
+ deliverLink: async (_ctx, { signerId, url }) => {
184
+ deliveredLinks.set(signerId, url);
185
+ },
186
+ });
187
+ ```