@gadicc/loom 1.16.1 → 1.18.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 (104) hide show
  1. package/README.md +74 -41
  2. package/deno.json +3 -0
  3. package/esm/_dnt.polyfills.d.ts +6 -0
  4. package/esm/_dnt.polyfills.d.ts.map +1 -1
  5. package/esm/mod.d.ts +2 -0
  6. package/esm/mod.d.ts.map +1 -1
  7. package/esm/mod.js +2 -0
  8. package/esm/src/cli/mod.d.ts +4 -2
  9. package/esm/src/cli/mod.d.ts.map +1 -1
  10. package/esm/src/cli/mod.js +2018 -369
  11. package/esm/src/cli/projectTooling.d.ts +138 -0
  12. package/esm/src/cli/projectTooling.d.ts.map +1 -0
  13. package/esm/src/cli/projectTooling.js +614 -0
  14. package/esm/src/mail/errors.d.ts +33 -0
  15. package/esm/src/mail/errors.d.ts.map +1 -0
  16. package/esm/src/mail/errors.js +89 -0
  17. package/esm/src/mail/memory.d.ts +30 -0
  18. package/esm/src/mail/memory.d.ts.map +1 -0
  19. package/esm/src/mail/memory.js +340 -0
  20. package/esm/src/mail/mod.d.ts +7 -0
  21. package/esm/src/mail/mod.d.ts.map +1 -0
  22. package/esm/src/mail/mod.js +6 -0
  23. package/esm/src/mail/postal.d.ts +57 -0
  24. package/esm/src/mail/postal.d.ts.map +1 -0
  25. package/esm/src/mail/postal.js +238 -0
  26. package/esm/src/mail/retry.d.ts +9 -0
  27. package/esm/src/mail/retry.d.ts.map +1 -0
  28. package/esm/src/mail/retry.js +19 -0
  29. package/esm/src/mail/service.d.ts +23 -0
  30. package/esm/src/mail/service.d.ts.map +1 -0
  31. package/esm/src/mail/service.js +185 -0
  32. package/esm/src/mail/types.d.ts +176 -0
  33. package/esm/src/mail/types.d.ts.map +1 -0
  34. package/esm/src/mail/types.js +1 -0
  35. package/esm/src/mui/mail.d.ts +29 -0
  36. package/esm/src/mui/mail.d.ts.map +1 -0
  37. package/esm/src/mui/mail.js +114 -0
  38. package/esm/src/mui/mailView.d.ts +20 -0
  39. package/esm/src/mui/mailView.d.ts.map +1 -0
  40. package/esm/src/mui/mailView.js +26 -0
  41. package/esm/src/mui/mod.d.ts +1 -0
  42. package/esm/src/mui/mod.d.ts.map +1 -1
  43. package/esm/src/mui/mod.js +1 -0
  44. package/esm/src/next/mail/mod.d.ts +3 -0
  45. package/esm/src/next/mail/mod.d.ts.map +1 -0
  46. package/esm/src/next/mail/mod.js +2 -0
  47. package/esm/src/next/mail/route.d.ts +12 -0
  48. package/esm/src/next/mail/route.d.ts.map +1 -0
  49. package/esm/src/next/mail/route.js +43 -0
  50. package/package.json +56 -2
  51. package/script/_dnt.polyfills.d.ts +6 -0
  52. package/script/_dnt.polyfills.d.ts.map +1 -1
  53. package/script/mod.d.ts +2 -0
  54. package/script/mod.d.ts.map +1 -1
  55. package/script/mod.js +2 -0
  56. package/script/src/cli/mod.d.ts +4 -2
  57. package/script/src/cli/mod.d.ts.map +1 -1
  58. package/script/src/cli/mod.js +2018 -369
  59. package/script/src/cli/projectTooling.d.ts +138 -0
  60. package/script/src/cli/projectTooling.d.ts.map +1 -0
  61. package/script/src/cli/projectTooling.js +634 -0
  62. package/script/src/mail/errors.d.ts +33 -0
  63. package/script/src/mail/errors.d.ts.map +1 -0
  64. package/script/src/mail/errors.js +97 -0
  65. package/script/src/mail/memory.d.ts +30 -0
  66. package/script/src/mail/memory.d.ts.map +1 -0
  67. package/script/src/mail/memory.js +345 -0
  68. package/script/src/mail/mod.d.ts +7 -0
  69. package/script/src/mail/mod.d.ts.map +1 -0
  70. package/script/src/mail/mod.js +22 -0
  71. package/script/src/mail/postal.d.ts +57 -0
  72. package/script/src/mail/postal.d.ts.map +1 -0
  73. package/script/src/mail/postal.js +245 -0
  74. package/script/src/mail/retry.d.ts +9 -0
  75. package/script/src/mail/retry.d.ts.map +1 -0
  76. package/script/src/mail/retry.js +22 -0
  77. package/script/src/mail/service.d.ts +23 -0
  78. package/script/src/mail/service.d.ts.map +1 -0
  79. package/script/src/mail/service.js +189 -0
  80. package/script/src/mail/types.d.ts +176 -0
  81. package/script/src/mail/types.d.ts.map +1 -0
  82. package/script/src/mail/types.js +2 -0
  83. package/script/src/mui/mail.d.ts +29 -0
  84. package/script/src/mui/mail.d.ts.map +1 -0
  85. package/script/src/mui/mail.js +159 -0
  86. package/script/src/mui/mailView.d.ts +20 -0
  87. package/script/src/mui/mailView.d.ts.map +1 -0
  88. package/script/src/mui/mailView.js +32 -0
  89. package/script/src/mui/mod.d.ts +1 -0
  90. package/script/src/mui/mod.d.ts.map +1 -1
  91. package/script/src/mui/mod.js +1 -0
  92. package/script/src/next/mail/mod.d.ts +3 -0
  93. package/script/src/next/mail/mod.d.ts.map +1 -0
  94. package/script/src/next/mail/mod.js +18 -0
  95. package/script/src/next/mail/route.d.ts +12 -0
  96. package/script/src/next/mail/route.d.ts.map +1 -0
  97. package/script/src/next/mail/route.js +46 -0
  98. package/skills/loom/SKILL.md +34 -22
  99. package/skills/loom-db/SKILL.md +9 -7
  100. package/skills/loom-db/references/db-stack.md +2 -1
  101. package/skills/loom-jobs/SKILL.md +9 -6
  102. package/skills/loom-lingui/SKILL.md +38 -0
  103. package/skills/loom-lingui/agents/openai.yaml +4 -0
  104. package/skills/loom-mail/SKILL.md +68 -0
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: loom-mail
3
+ description: Use when the task mentions the Loom mail feature, Postal outgoing mail or signed webhooks, mail outbox jobs, or admin test mail.
4
+ ---
5
+
6
+ # Loom mail
7
+
8
+ Use this skill together with the global `loom` skill. Read `loom.json` before
9
+ changing a consumer and treat `features.mail.config` as the path/provider/UI
10
+ contract.
11
+
12
+ ## Ownership
13
+
14
+ - Keep message rendering and domain delivery policy in the consumer.
15
+ - Use `@gadicc/loom/mail` for enqueue/lease/retry/event orchestration.
16
+ - Use `@gadicc/loom/mail/postal` for Postal HTTP and signed webhook behavior.
17
+ - Keep the Drizzle repository and migrations app-local. Never hide migrations
18
+ inside Loom.
19
+ - Preserve `authorizeMailAdmin()` on every admin page and server action. The
20
+ generated implementation intentionally denies all access until the app wires a
21
+ fresh session and admin-role check.
22
+
23
+ ## Adding mail
24
+
25
+ 1. Ensure Loom DB and auth features are active.
26
+ 2. Run `loom add mail`.
27
+ 3. Review the materialized schema and generate the app-local migration.
28
+ 4. Replace the generated deny-all access function with the app's admin check.
29
+ 5. Configure `POSTAL_API_KEY`, `POSTAL_HOST`, `POSTAL_FROM_EMAIL`, and
30
+ `POSTAL_WEBHOOK_PUBLIC_KEYS`. The last value is a JSON array of RSA public
31
+ JWKs with `kid`; it is not a shared secret.
32
+ 6. If jobs is active, register the generated `mail-drain` module in the app's
33
+ full and metadata catalogs and choose an app-owned schedule.
34
+ 7. Configure Postal to POST signed events to the generated webhook route.
35
+ 8. Run `loom check`; use `loom check --production` before release.
36
+
37
+ ## Delivery invariants
38
+
39
+ - Repository claim and completion methods are atomic transaction boundaries.
40
+ - A completion must match message id plus lease token.
41
+ - Postal API acceptance means `sent`, not `delivered`.
42
+ - Track provider ids and events per recipient.
43
+ - Deduplicate webhook events by provider plus event UUID.
44
+ - Verify the exact raw body with `X-Postal-Signature-KID` and
45
+ `X-Postal-Signature-256` before parsing.
46
+ - Treat timeout/network retries as at-least-once ambiguity; do not claim Postal
47
+ supports an idempotency key.
48
+ - Bound attachment size at the app/action boundary and never log attachment
49
+ bodies, API keys, or webhook key material.
50
+
51
+ ## Testing
52
+
53
+ - Use the memory repository/transport for lease, retry, cancellation, and
54
+ provider-event tests.
55
+ - Test the app-local Drizzle repository with its PGlite harness, especially live
56
+ lease exclusion, expired lease recovery, stale completion, and event replay.
57
+ - Sign webhook fixtures with an ephemeral RSA test key; do not bypass signature
58
+ verification in route tests.
59
+ - Verify the admin test-mail action rejects non-admin sessions.
60
+
61
+ ## AptHunt compatibility
62
+
63
+ Keep AptHunt's watchlist renderer and notification-delivery claim/backoff logic
64
+ local. Its `sendEmail` export may remain as a thin compatibility wrapper over
65
+ the Loom service. Preserve `/admin/emails` and its test/one-off-mail workflow.
66
+
67
+ Inbound mail and reply threading are planned follow-ups; do not infer a mailbox
68
+ or thread schema until a consumer supplies concrete routing requirements.