@jskit-ai/agent-docs 0.1.257 → 0.1.258

package/skills/jskit/references/patterns/workspaces/workspace-server/PATTERN.md

@@ -24,8 +24,8 @@ Choose workspace creation policy, roles, invitation policy, expiry, email copy,
 member permissions, personal-workspace behavior, and surface access rules.
 
 In `workspaces` mode, `tenancyPolicy.workspace.autoProvision: true` gives every
-user a personal workspace in addition to shared ones; the server config function
-`personalWorkspaceName(user)` names it. `workspaceSettings.defaults` sets
+user a personal workspace in addition to shared ones; the optional
+`workspaces.personal-workspace-name` capability, a function of the user, names it. `workspaceSettings.defaults` sets
 `invitesEnabled` and the colours (`lightPrimaryColor`, `darkPrimaryColor` and
 the other palette fields) that new workspaces start with.
 
@@ -63,16 +63,16 @@ catalogue entries. Updating labels requires no database migration.
 
 ## Transactional invitation participation
 
-Through `workspaces.core`, register one callback during feature setup with
-`workspaces.services.pendingInvitations.registerAcceptanceParticipant(fn)`.
-The built-in `workspace.invite.redeem` action invokes
-`fn({ invite, user }, { trx, context })` after validating the recipient, state and
-expiry and activating membership in the uncommitted transaction. Forward `trx`
-to every application owner and propagate failures. JSKIT marks accepted and
-commits after the callback succeeds. Keep external effects out of the callback.
-Registration rejects non-functions, duplicates and calls after acceptance/refusal
-begins. Allow ordinary invitations; reject stale, revoked, conflicting or
-unexpectedly missing application associations.
+Provide one function as the optional `workspaces.invite-acceptance-participant`
+capability, from a small application feature that requires only what its writes
+need (it cannot require `workspaces.core`, which receives it). The built-in
+`workspace.invite.redeem` action invokes `fn({ invite, user }, { trx, context })`
+after validating the recipient, state and expiry and activating membership in the
+uncommitted transaction. Forward `trx` to every application owner and propagate
+failures. JSKIT marks accepted and commits after the function succeeds. Keep
+external effects out of it. Without the capability, acceptance activates the
+membership only. Allow ordinary invitations; reject stale, revoked, conflicting
+or unexpectedly missing application associations.
 
 Use `members.prepareInvite(workspace, actor,
 payload, { trx, context })` in `repositories.workspaceInvites.withTransaction`
@@ -91,8 +91,8 @@ exception, or the normalized mailer result. Persistence is unchanged by delivery
 failure. A provider may accept a message before failing; the application owns
 receipts and retries. Keep tokens/URLs out of logs and use controlled mailers in tests.
 
-`createInvite`, acceptance and refusal now own managed transactions and reject
-borrowed `options.trx`. Use preparation followed by delivery after commit for
+`createInvite`, acceptance and refusal own their managed transactions and
+reject a borrowed `options.trx`. Use preparation followed by delivery after commit for
 transactional creation; put related acceptance writes in the participant. Revocation may join
 a managed transaction. Raw Knex/savepoint transactions cannot own resource
 writes. Invitation mutations lock workspace then invitation rows, revalidate
@@ -115,9 +115,34 @@ authorization, identity/training linking, scope eligibility and required audit.
 
 ## Example files
 
-`example/config/roles.js` is a concrete role catalogue.
-`example/packages/main/src/server/email/workspaceInviteEmail.js` demonstrates an
-app-owned invitation renderer. Compose both through normal application config.
+`example/config/roles.js` is a concrete role catalogue, set as the
+application's `roleCatalog` config.
+
+The invitation email comes from two optional `workspaces.core` capabilities,
+which one small application feature provides:
+`example/packages/main/src/server/WorkspaceInvitationsFeature.js`.
+
+```js
+provides: {
+  inviteEmailTemplate: "workspaces.invite-email-template",
+  inviteMailer: "workspaces.invite-mailer"
+},
+setup({ env }) {
+  return {
+    inviteEmailTemplate: renderWorkspaceInviteEmail,
+    inviteMailer: createWorkspaceInviteMailer({ env })
+  };
+}
+```
+
+- `email/workspaceInviteEmail.js` is the renderer, a
+  `WorkspaceInviteEmailTemplate` returning `{ subject, text, html }`.
+- `email/workspaceInviteMailer.js` is the mailer, a `WorkspaceInviteMailer`
+  whose `sendWorkspaceInvite` sends the rendered message over SMTP.
+
+Without a renderer, workspaces-core uses its built-in email; without a mailer,
+invitations are created and their delivery reports `mailer_unconfigured`. The
+feature must not require `workspaces.core`, which receives both.
 
 ## Variation points
 

package/skills/jskit/references/patterns/workspaces/workspace-server/example/packages/main/src/server/WorkspaceInvitationsFeature.js

@@ -0,0 +1,27 @@
+import { defineFeature } from "@jskit-ai/kernel/server/features";
+import { renderWorkspaceInviteEmail } from "./email/workspaceInviteEmail.js";
+import { createWorkspaceInviteMailer } from "./email/workspaceInviteMailer.js";
+
+/**
+ * The application's invitation email: the renderer and the mailer that sends
+ * it, each filling one of workspaces-core's optional tokens.
+ */
+const WorkspaceInvitationsFeature = defineFeature({
+  id: "main.workspace-invitations",
+  requires: {
+    env: "runtime.env"
+  },
+  provides: {
+    inviteEmailTemplate: "workspaces.invite-email-template",
+    inviteMailer: "workspaces.invite-mailer"
+  },
+  /** @param {{ env: import("@jskit-ai/kernel/server/types").RuntimeEnv }} capabilities */
+  setup({ env }) {
+    return {
+      inviteEmailTemplate: renderWorkspaceInviteEmail,
+      inviteMailer: createWorkspaceInviteMailer({ env })
+    };
+  }
+});
+
+export { WorkspaceInvitationsFeature };

package/skills/jskit/references/patterns/workspaces/workspace-server/example/packages/main/src/server/email/workspaceInviteEmail.js

@@ -1,13 +1,14 @@
-function renderWorkspaceInviteEmail({
-  inviteUrl = "",
-  workspace = {},
-  inviter = null,
-  roleSid = "member",
-  expiresAt = ""
-} = {}) {
-  const workspaceName = String(workspace?.name || workspace?.slug || "the workspace").trim() || "the workspace";
-  const inviterName = String(inviter?.displayName || inviter?.email || "").trim();
-  const roleName = String(roleSid || "member").trim() || "member";
+/**
+ * The application's invitation email, provided as
+ * `workspaces.invite-email-template`. workspaces-core passes every field; the
+ * inviter is null when no one is signed in, and `roleLabel` is present only
+ * when the role catalogue names the role.
+ * @type {import("@jskit-ai/workspaces-core/server/types").WorkspaceInviteEmailTemplate}
+ */
+function renderWorkspaceInviteEmail({ inviteUrl, workspace, inviter, roleSid, roleLabel, expiresAt }) {
+  const workspaceName = workspace.name || workspace.slug;
+  const inviterName = inviter?.displayName || inviter?.email || "";
+  const roleName = roleLabel || roleSid;
   const intro = inviterName
     ? `${inviterName} invited you to join ${workspaceName} as ${roleName}.`
     : `You have been invited to join ${workspaceName} as ${roleName}.`;

package/skills/jskit/references/patterns/workspaces/workspace-server/example/packages/main/src/server/email/workspaceInviteMailer.js

@@ -0,0 +1,27 @@
+import nodemailer from "nodemailer";
+
+/**
+ * The application's `workspaces.invite-mailer`: sends each rendered
+ * invitation through the SMTP server `SMTP_URL` names, from `MAIL_FROM`.
+ * @param {object} dependencies
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} dependencies.env
+ * @returns {import("@jskit-ai/workspaces-core/server/types").WorkspaceInviteMailer}
+ */
+function createWorkspaceInviteMailer({ env }) {
+  const transport = nodemailer.createTransport(env.SMTP_URL);
+
+  async function sendWorkspaceInvite({ email, message }) {
+    const sent = await transport.sendMail({
+      from: env.MAIL_FROM,
+      to: email,
+      subject: message.subject,
+      text: message.text,
+      ...(message.html ? { html: message.html } : {})
+    });
+    return { status: "sent", providerMessageId: sent.messageId };
+  }
+
+  return Object.freeze({ sendWorkspaceInvite });
+}
+
+export { createWorkspaceInviteMailer };

package/skills/jskit/references/translation.md

@@ -1,4 +1,4 @@
-<!-- Generated from `packages/agent-docs/site/guide/framework/translation.md` by `npm run agent-docs:build`. -->
+<!-- Generated from `packages/agent-docs/site/guide/framework/translation.md`. -->
 
 # Translating a JSKIT app
 
@@ -140,9 +140,10 @@ the English `message`:
   `messageParams` for the exact sentence.
 
 The client translates a code only when the English the server sent is JSKIT's
-English for that code. An app's own sentence under a shared code (for example
-`throw new NotFoundError("Contact not found.")`) is shown exactly as written, and
-so is any text whose code has no catalog entry.
+English for that code. An app's own sentence under JSKIT's shared code is shown
+exactly as written, and so is any text whose code has no catalog entry. That is
+why each refusal an app throws
+[carries its own code](typed-features.md#refusals-carry-their-own-code).
 
 App code that shows errors uses the same helper JSKIT's components use: