@fias/create-fias-plugin 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "publishConfig": {
     "access": "public"
   },

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.22.0 -->
+<!-- fias-sdk-guide-version: 2.23.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -1308,6 +1308,36 @@ Three things to design around:
 
 Only images the user made or uploaded in **their own** Fias files can be published (pass the `fileId` from a `useImageGeneration()` result). PNG/JPEG/WebP only; every image is re-encoded to a canonical PNG with metadata stripped. Publishers can `unpublish()` their own assets, and any user can `report()` one for review.
 
+### `useCompanyEmail()` — Send email as the Company the app is used in
+
+**Permission:** `email:company:send`
+**Returns:** `CompanyEmailApi`
+
+For apps built for an approved partner Company: send email **from the Company's own verified domain** (e.g. `team@example.com`), not from Fias. Declaring the permission is not enough — a Company admin must also authorize your app to send, and chooses who it may email: members of the workspace it is used in, members of the whole Company, or anyone. Until then every call is refused with `COMPANY_EMAIL_NOT_AUTHORIZED`.
+
+```tsx
+import { useCompanyEmail } from '@fias/arche-sdk';
+
+const email = useCompanyEmail();
+const { results, sent } = await email.send({
+  requestKey: `digest-${weekId}`, // reuse on retry — never double-sends
+  to: members.map((m) => ({ userId: m.userId })),
+  subject: 'Your weekly digest',
+  text: digestText, // required
+  html: digestHtml, // optional, sanitized
+});
+// results[i]: { index, status: 'accepted' | 'unknown' | 'failed' | 'muted' | 'not_sent' }
+```
+
+- **You never choose the From address** — it is the address the Company assigned your app. You choose recipients and content.
+- **Name members by `userId`**; you never see their addresses. Raw `{ email }` recipients work only if the Company let your app email anyone. One recipient outside what the Company allowed refuses the whole call (without saying which).
+- **The user must be working in one of the Company's workspaces, with edit access.** Each recipient is charged to that user, like any paid call; up to 50 recipients per call, and a daily limit per app per Company.
+- **Retry with the same `requestKey`.** A recipient already sent under that key is not sent again. `unknown` means it may have gone out — do not resend it under a new key.
+- **HTML is sanitized** to the email allow-list: tables, inline presentational styles, `https` images and `https`/`mailto` links are kept; `<script>`, `<form>`, `<iframe>` and similar refuse the send (`EMAIL_CONTENT_REJECTED`).
+- **Attachments:** up to 5 files, 5 MB total, and only `.pdf`, `.png`, `.jpg`/`.jpeg`, `.gif`, `.csv`, `.txt`, `.ics`, `.docx`, `.xlsx`. `contentType` must match the extension (e.g. `application/pdf`), and the bytes must be that format; anything else refuses the send (`EMAIL_CONTENT_REJECTED`).
+- **Every email carries one-click unsubscribe.** Recipients who used it come back as `muted`; the Company may also show a "Stop emails from this arche" line, which is always shown for `kind: 'marketing'`.
+- Not available in the builder preview or the local dev harness — it sends real email. Other refusals: `WORKSPACE_REQUIRED`, `RECIPIENT_NOT_ALLOWED`, `COMPANY_EMAIL_UNAVAILABLE` (the Company's domain is not ready or paused), `DAILY_EMAIL_LIMIT_REACHED`, `INSUFFICIENT_CREDITS`.
+
 ### `useFiasStore()` — In-app purchases (IAP)
 
 **Permission:** `store:purchase`
@@ -1405,7 +1435,23 @@ the user moves the host themselves with browser back/forward. So a router
 driven off `currentPath` stays in step with the address bar, and the back
 button works the way your users expect — you do not have to mirror the path in
 your own state. The dev harness echoes navigations the same way, so what you
-see locally is what ships.
+see locally is what ships. To test a deep link locally, open the harness with
+`?path=/map` (a root-relative path in your route space) and `currentPath`
+starts there instead of at `/`.
+
+**Correcting the URL.** Every `navigateTo` pushes a history entry by default,
+which is right for navigation the user asked for. When you are CORRECTING the
+address bar instead — normalizing a link you were opened at (`/Map/` →
+`/map`), or putting it back after refusing a route — pass `{ replace: true }`
+so Back does not land on the URL you just corrected:
+
+```tsx
+navigateTo('/map', { replace: true });
+```
+
+A host older than this option ignores it and pushes. If you correct paths
+automatically as they arrive, never repeat the same correction twice in a
+row, or a push-only host can trap the Back button between two URLs.
 
 ### Opening external links
 

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.22.0 -->
+<!-- fias-sdk-guide-version: 2.23.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -1308,6 +1308,36 @@ Three things to design around:
 
 Only images the user made or uploaded in **their own** Fias files can be published (pass the `fileId` from a `useImageGeneration()` result). PNG/JPEG/WebP only; every image is re-encoded to a canonical PNG with metadata stripped. Publishers can `unpublish()` their own assets, and any user can `report()` one for review.
 
+### `useCompanyEmail()` — Send email as the Company the app is used in
+
+**Permission:** `email:company:send`
+**Returns:** `CompanyEmailApi`
+
+For apps built for an approved partner Company: send email **from the Company's own verified domain** (e.g. `team@example.com`), not from Fias. Declaring the permission is not enough — a Company admin must also authorize your app to send, and chooses who it may email: members of the workspace it is used in, members of the whole Company, or anyone. Until then every call is refused with `COMPANY_EMAIL_NOT_AUTHORIZED`.
+
+```tsx
+import { useCompanyEmail } from '@fias/arche-sdk';
+
+const email = useCompanyEmail();
+const { results, sent } = await email.send({
+  requestKey: `digest-${weekId}`, // reuse on retry — never double-sends
+  to: members.map((m) => ({ userId: m.userId })),
+  subject: 'Your weekly digest',
+  text: digestText, // required
+  html: digestHtml, // optional, sanitized
+});
+// results[i]: { index, status: 'accepted' | 'unknown' | 'failed' | 'muted' | 'not_sent' }
+```
+
+- **You never choose the From address** — it is the address the Company assigned your app. You choose recipients and content.
+- **Name members by `userId`**; you never see their addresses. Raw `{ email }` recipients work only if the Company let your app email anyone. One recipient outside what the Company allowed refuses the whole call (without saying which).
+- **The user must be working in one of the Company's workspaces, with edit access.** Each recipient is charged to that user, like any paid call; up to 50 recipients per call, and a daily limit per app per Company.
+- **Retry with the same `requestKey`.** A recipient already sent under that key is not sent again. `unknown` means it may have gone out — do not resend it under a new key.
+- **HTML is sanitized** to the email allow-list: tables, inline presentational styles, `https` images and `https`/`mailto` links are kept; `<script>`, `<form>`, `<iframe>` and similar refuse the send (`EMAIL_CONTENT_REJECTED`).
+- **Attachments:** up to 5 files, 5 MB total, and only `.pdf`, `.png`, `.jpg`/`.jpeg`, `.gif`, `.csv`, `.txt`, `.ics`, `.docx`, `.xlsx`. `contentType` must match the extension (e.g. `application/pdf`), and the bytes must be that format; anything else refuses the send (`EMAIL_CONTENT_REJECTED`).
+- **Every email carries one-click unsubscribe.** Recipients who used it come back as `muted`; the Company may also show a "Stop emails from this arche" line, which is always shown for `kind: 'marketing'`.
+- Not available in the builder preview or the local dev harness — it sends real email. Other refusals: `WORKSPACE_REQUIRED`, `RECIPIENT_NOT_ALLOWED`, `COMPANY_EMAIL_UNAVAILABLE` (the Company's domain is not ready or paused), `DAILY_EMAIL_LIMIT_REACHED`, `INSUFFICIENT_CREDITS`.
+
 ### `useFiasStore()` — In-app purchases (IAP)
 
 **Permission:** `store:purchase`
@@ -1405,7 +1435,23 @@ the user moves the host themselves with browser back/forward. So a router
 driven off `currentPath` stays in step with the address bar, and the back
 button works the way your users expect — you do not have to mirror the path in
 your own state. The dev harness echoes navigations the same way, so what you
-see locally is what ships.
+see locally is what ships. To test a deep link locally, open the harness with
+`?path=/map` (a root-relative path in your route space) and `currentPath`
+starts there instead of at `/`.
+
+**Correcting the URL.** Every `navigateTo` pushes a history entry by default,
+which is right for navigation the user asked for. When you are CORRECTING the
+address bar instead — normalizing a link you were opened at (`/Map/` →
+`/map`), or putting it back after refusing a route — pass `{ replace: true }`
+so Back does not land on the URL you just corrected:
+
+```tsx
+navigateTo('/map', { replace: true });
+```
+
+A host older than this option ignores it and pushes. If you correct paths
+automatically as they arrive, never repeat the same correction twice in a
+row, or a push-only host can trap the Back button between two URLs.
 
 ### Opening external links