@fias/create-fias-plugin 1.23.0 → 1.24.0

package/package.json

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

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.31.0 -->
+<!-- fias-sdk-guide-version: 2.32.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -173,9 +173,13 @@ pairings instead of the flat catalog, see `FONT_PAIRINGS`.
 import { useFiasUser } from '@fias/arche-sdk';
 
 const user = useFiasUser();
-// { userId: string, displayName: string, avatar: string | null }
+// { ref: string, displayName: string, avatar: string | null }
 ```
 
+`ref` is your app's identifier for this person (`aur_…`): the same everywhere in your app, different
+in every other app. Store it wherever your data names a person. Apps that existed before refs also
+get a deprecated `userId`; new apps never do. In the dev harness, Mock mode gives the mock user a stable ref, and Live mode the ref the platform allocated for you; set `"mockUser": { "legacyUserId": true }` in `fias-dev.config.json` to also get `userId`, as an app from before refs does.
+
 ### `useFiasHolder()` — The Fias workspace the app was opened in
 
 **Permission:** `user:profile:read` or `data:workspace`
@@ -336,6 +340,7 @@ A collection can carry rules the platform checks on **every** write, so a buggy
 - **`nonNegative`**: these numeric fields must be ≥ 0 when present.
 - **`fieldBounds`**: `field <op> bound`, where `op` is `eq` / `ne` / `lt` / `lte` / `gt` / `gte` and the bound is a constant `value` or a sibling field `valueField` (exactly one).
 - **`immutableFields`**: set once; an overwrite must carry the same value.
+- **`personFields`**: these fields name people. Each holds one app user ref (`useFiasUser().ref`) or a list of up to 20, never a name, username or id. Declare every field your data uses for a person: it is what lets Fias relate records to people and carry refs safely between apps.
 - **`references`**: `field` holds the key of a document that must exist in `collection`, in the same scope (same workspace, same user, or shared). An absent or null field is allowed. The writer must be able to read the target collection. Deleting a document that something still references is refused; there is no cascade.
 - **`ledgerSums`**: a counter `field` may change only by exactly the sum of the rows appended to `ledger` in the **same write**. A ledger row counts toward the counter whose key its term's `key` field holds, adding its `amount` (subtracted with `negate: true`, filtered with `when: { field, in: [...] }`). A counter that moves without rows, and rows whose counter did not move by their sum, are both refused. The ledger must be `appendOnly` and have the counter's scope; an absent counter counts as 0. At most 4 terms per rule.
 
@@ -599,7 +604,8 @@ function Team() {
 
   async function setup() {
     const ws = await workspaces.create('Acme Corp'); // caller becomes owner
-    await workspaces.addMember(ws.workspaceId, 'alice', 'member'); // members are addressed by username
+    // Fias shows the person a sheet; they choose who to add. You get refs back.
+    const { added } = await workspaces.addPeople(ws.workspaceId, { role: 'member' });
 
     // Workspace-scoped collection + document (role-gated server-side).
     await dataStore.createCollection('ledger', { userScope: 'workspace' });
@@ -613,7 +619,8 @@ function Team() {
     );
 
     const mine = await workspaces.list(); // workspaces I belong to
-    const members = await workspaces.listMembers(ws.workspaceId);
+    const members = await workspaces.listMembers(ws.workspaceId); // [{ ref, displayName, role, … }]
+    await workspaces.updateMember(ws.workspaceId, { ref: members[1].ref }, 'admin');
   }
 }
 ```
@@ -628,7 +635,14 @@ if (holder?.type === 'org') {
 }
 ```
 
-**Methods:** `create`, `openForWorkspace`, `list`, `get`, `archive` (owner only — final: an archived workspace cannot be reopened, and it is deleted with its documents 30 days later; say so before your user archives), `listMembers`, `addMember`, `updateMember`, `removeMember`. `addMember(workspaceId, username, role, expiresAt?)` accepts an optional ISO-8601 `expiresAt` to grant **time-bounded** access (e.g. a contractor seat) — owners cannot expire; an expired member is treated as no longer a member. **Rate limits (per minute):** `create`/`archive` 20, member ops 30, `list`/`get`/`listMembers` 120. **Error codes:** `NOT_A_MEMBER`, `FORBIDDEN`, `ROLE_CEILING`, `MUST_KEEP_ONE_OWNER`, `WORKSPACE_NOT_FOUND`, `HOLDER_BACKED_WORKSPACE`, `HOLDER_NOT_ELIGIBLE`. Read workspace documents with `useFiasDataStore().get`/`query`/`search` passing `{ workspaceId }` (every active member can read; make the collection `searchable` to use `search`). **Per-collection role floors:** raise a workspace collection's minimum role at creation — `createCollection('board_minutes', { userScope: 'workspace', writeMinRole: 'admin', readMinRole: 'member' })` makes that collection admin-write / member-read, above the default (write ≥ member, read ≥ viewer).
+**Naming people.** Store `useFiasUser().ref` wherever your data names a person (an assignee, an "uploaded by"), and turn refs back into names with `resolvePeople(refs, workspaceId)`: up to 100 at a time, in order, each `{ ref, displayName, avatar }` or `null`. A ref is named only while it belongs to a current member of that workspace — someone who left, an unknown ref or another app's ref is `null`, and you can't tell which. Without `workspaceId` only the user's own ref resolves. In a Fias org workspace, names also need the `data:workspace-people:read` permission (human-reviewed) **and** the workspace's approval of your app covering it; without both every ref is `null`, so show a neutral label. Names never come with an id or an email.
+
+```tsx
+const [assignee] = await workspaces.resolvePeople([task.assigneeRef], shared.workspaceId);
+const label = assignee?.displayName ?? 'Former member';
+```
+
+**Methods:** `create`, `openForWorkspace`, `list`, `get`, `archive` (owner only — final: an archived workspace cannot be reopened, and it is deleted with its documents 30 days later; say so before your user archives), `listMembers`, `addPeople`, `updateMember`, `removeMember`, `resolvePeople`. **Add people with `addPeople(workspaceId, { role? })`**: Fias draws a sheet in which the person picks co-members of their Fias workspace or types an exact username, and may change the role (you suggest `'admin'`, `'member'` or `'viewer'`); it resolves with `{ added: [{ ref, displayName, role }] }` — empty if they added no one. Your code never names who to add. (`addMember(workspaceId, username, …)` is deprecated: it works only for apps from before app user refs, and in the dev harness and Forge test channel; elsewhere it rejects with `ADD_MEMBER_USE_SHEET`.) Members come back named by your app's `ref` for them and their `displayName` — never a username or id — and `updateMember` / `removeMember` take that `{ ref }`. **Rate limits (per minute):** `create`/`archive` 20, member ops 30, `list`/`get`/`listMembers`/`resolvePeople` 120. **Error codes:** `NOT_A_MEMBER`, `FORBIDDEN`, `ROLE_CEILING`, `ADD_PEOPLE_UNAVAILABLE` (no sheet here: the Forge test channel, Company portals), `MEMBER_TARGET_USE_REF` (name members by `{ ref }`), `SHEET_BUSY`, `MUST_KEEP_ONE_OWNER`, `WORKSPACE_NOT_FOUND`, `HOLDER_BACKED_WORKSPACE`, `HOLDER_NOT_ELIGIBLE`. Read workspace documents with `useFiasDataStore().get`/`query`/`search` passing `{ workspaceId }` (every active member can read; make the collection `searchable` to use `search`). **Per-collection role floors:** raise a workspace collection's minimum role at creation — `createCollection('board_minutes', { userScope: 'workspace', writeMinRole: 'admin', readMinRole: 'member' })` makes that collection admin-write / member-read, above the default (write ≥ member, read ≥ viewer).
 
 ### `useFiasAccess()` — The current user's own access in a workspace
 
@@ -1785,6 +1799,45 @@ await connections.release(connectionId); // give up your own access (owners and
 
 A person connects an outside account (X: `'x'`, LinkedIn: `'linkedin'`) to a Fias workspace — their personal one, or an organization's, where only owners and admins can — and lets your app use it. Your app **never sees a credential**: `connect(provider)` opens a screen the platform draws (it offers the workspace's existing accounts for that provider, or connects a new one in a popup) and resolves with the connection the person chose, or `{ canceled: true }`. `list()` returns only the accounts the workspace the app is open in lets it use; one with `status: 'needs_reconnect'` needs the person to connect it again. People manage connections and every app's access in Workspace Controls. `release` gives up the app's access for the whole workspace, so only the workspace's owners and admins may call it (`ROLE_NOT_ALLOWED` otherwise). Not available in the builder preview or the test channel. **Error codes:** `CONNECTION_NOT_FOUND`, `PERMISSION_DENIED`, `CONNECT_UNAVAILABLE`, `ROLE_NOT_ALLOWED`.
 
+### `useFiasWebSources()` — Read pages on Fias-approved websites, as data
+
+**Permission:** `web:sources:read` (human-reviewed at publish)
+**Returns:** `FiasWebSourcesApi`
+
+```tsx
+import { useFiasWebSources } from '@fias/arche-sdk';
+
+const web = useFiasWebSources();
+const { sites } = await web.listSites({ category: 'credit_union', search: 'becu' });
+// [{ host: 'www.becu.org', name: 'BECU', category: 'credit_union' }]
+const result = await web.extract({
+  url: 'https://www.becu.org/everyday-banking/certificates',
+  form: {
+    description: 'Share certificate rates',
+    fields: {
+      asOf: { kind: 'date', description: 'Date the rates are effective, if stated' },
+      rates: {
+        kind: 'list',
+        maxItems: 50,
+        item: {
+          product: { kind: 'enum', values: ['certificate', 'ira_certificate', 'other'] },
+          months: { kind: 'integer', min: 1, max: 120, description: 'Term in months' },
+          apy: { kind: 'number', min: 0, max: 25, description: 'APY in percent' },
+        },
+      },
+    },
+  },
+  maxAgeSeconds: 24 * 3600,
+});
+// result.data.rates, result.site.name, result.fetchedAt, result.fromCache, result.discarded
+```
+
+Your app reads pages only on **websites Fias approved** (regulated institutions such as credit unions and banks, and government sites) — any page on an approved site, so a redesigned or moved page keeps working. To have a site approved, ask Fias. `listSites()` lists them (free).
+
+`extract()` never returns the page's text — not even a short label. You send a **form** — up to 30 fields of kinds `number` and `integer` (optional `min`/`max`), `boolean`, `date` (`YYYY-MM-DD`), `enum` (your own `values`) and `list` (up to 200 rows of those) — and Fias reads the page into it. There is no free-text kind: describe what you need as numbers, dates, yes/no and choices you list (a product type, not a product name). Every value may be `null` (the page did not say); a value that broke its field's rules comes back `null` and is named in `discarded`. URLs must be `https://`; `redirected: true` means the site moved the page within itself (the new address is not returned). The reader fills the form from whatever layout the page has, but it never runs JavaScript: a page that builds its figures with scripts comes back with `scriptHeavy: true` and mostly nulls — read the site's PDF rate sheet instead.
+
+One copy of each page serves every app, and a page is fetched from its site **at most once an hour**. `maxAgeSeconds` (default one day, 3600–30 days) is the oldest copy you accept. A fresh fetch (about a tenth of a cent) and the reading (a fast model's tokens — well under a cent for a typical page) are charged to the user; a cached result costs nothing (`fromCache: true`). `stale: true` means the site could not be asked again just now and you got the last copy. Always show `site.name` and `fetchedAt` beside the figures. Not available in the builder preview or the test channel. **Error codes:** `WEB_SOURCES_DISABLED`, `INVALID_URL`, `SITE_NOT_APPROVED`, `PAGE_EXCLUDED` (a part of the site where the public posts), `ROBOTS_DISALLOWED`, `FETCH_FAILED`, `RESPONSE_TOO_LARGE`, `CONTENT_TYPE_NOT_ALLOWED`, `EXTRACTION_FAILED`, `SOURCE_BUSY`, `RATE_LIMIT` (surface it, never retry in a loop), `INSUFFICIENT_CREDITS`, `PERMISSION_DENIED`.
+
 ### `useFiasX()` / `useFiasLinkedIn()` — Act as a connected account
 
 **Permission:** `connections:use` (human-reviewed at publish)
@@ -1844,7 +1897,7 @@ 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 })),
+  to: assigneeRefs.map((ref) => ({ ref })), // refs your app stored (useFiasUser().ref)
   subject: 'Your weekly digest',
   text: digestText, // required
   html: digestHtml, // optional, sanitized
@@ -1853,7 +1906,7 @@ const { results, sent } = await email.send({
 ```
 
 - **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).
+- **Name members by their ref** (`{ ref }` — see Naming people under `useFiasWorkspaces()`); you never see their addresses. A ref that names no one is refused exactly like a member outside what the Company allowed. `{ userId }` is deprecated and accepted only from apps that existed before refs. 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`).
@@ -2319,7 +2372,7 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 
 Other optional sub-fields: `currency: "usd"` (only USD supported today), `platformFeePercent` (override the default platform cut — non-standard).
 
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `storage:local`, `data:store`, `data:search`, `data:workspace`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `vault:user-documents:read`, `vault:user-documents:write`, `vault:user-documents:edit`, `vault:workspace-documents:read`, `vault:creative:read`, `vault:creative:write`, `opener:send`, `assets:read`, `assets:community:read`, `assets:community:publish`, `litcraft:hub`, `navigation:open_arche`, `sandbox:vendored-libraries`, `ai:actions`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `storage:local`, `data:store`, `data:search`, `data:workspace`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `vault:user-documents:read`, `vault:user-documents:write`, `vault:user-documents:edit`, `vault:workspace-documents:read`, `vault:creative:read`, `vault:creative:write`, `opener:send`, `assets:read`, `assets:community:read`, `assets:community:publish`, `litcraft:hub`, `navigation:open_arche`, `sandbox:vendored-libraries`, `ai:actions`, `connections:use`, `schedule:invoke`, `web:sources:read`
 
 **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID (or a `{ capability }` selector, or an entry from `useTextModels()`) and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
 

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.31.0 -->
+<!-- fias-sdk-guide-version: 2.32.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -173,9 +173,13 @@ pairings instead of the flat catalog, see `FONT_PAIRINGS`.
 import { useFiasUser } from '@fias/arche-sdk';
 
 const user = useFiasUser();
-// { userId: string, displayName: string, avatar: string | null }
+// { ref: string, displayName: string, avatar: string | null }
 ```
 
+`ref` is your app's identifier for this person (`aur_…`): the same everywhere in your app, different
+in every other app. Store it wherever your data names a person. Apps that existed before refs also
+get a deprecated `userId`; new apps never do. In the dev harness, Mock mode gives the mock user a stable ref, and Live mode the ref the platform allocated for you; set `"mockUser": { "legacyUserId": true }` in `fias-dev.config.json` to also get `userId`, as an app from before refs does.
+
 ### `useFiasHolder()` — The Fias workspace the app was opened in
 
 **Permission:** `user:profile:read` or `data:workspace`
@@ -336,6 +340,7 @@ A collection can carry rules the platform checks on **every** write, so a buggy
 - **`nonNegative`**: these numeric fields must be ≥ 0 when present.
 - **`fieldBounds`**: `field <op> bound`, where `op` is `eq` / `ne` / `lt` / `lte` / `gt` / `gte` and the bound is a constant `value` or a sibling field `valueField` (exactly one).
 - **`immutableFields`**: set once; an overwrite must carry the same value.
+- **`personFields`**: these fields name people. Each holds one app user ref (`useFiasUser().ref`) or a list of up to 20, never a name, username or id. Declare every field your data uses for a person: it is what lets Fias relate records to people and carry refs safely between apps.
 - **`references`**: `field` holds the key of a document that must exist in `collection`, in the same scope (same workspace, same user, or shared). An absent or null field is allowed. The writer must be able to read the target collection. Deleting a document that something still references is refused; there is no cascade.
 - **`ledgerSums`**: a counter `field` may change only by exactly the sum of the rows appended to `ledger` in the **same write**. A ledger row counts toward the counter whose key its term's `key` field holds, adding its `amount` (subtracted with `negate: true`, filtered with `when: { field, in: [...] }`). A counter that moves without rows, and rows whose counter did not move by their sum, are both refused. The ledger must be `appendOnly` and have the counter's scope; an absent counter counts as 0. At most 4 terms per rule.
 
@@ -599,7 +604,8 @@ function Team() {
 
   async function setup() {
     const ws = await workspaces.create('Acme Corp'); // caller becomes owner
-    await workspaces.addMember(ws.workspaceId, 'alice', 'member'); // members are addressed by username
+    // Fias shows the person a sheet; they choose who to add. You get refs back.
+    const { added } = await workspaces.addPeople(ws.workspaceId, { role: 'member' });
 
     // Workspace-scoped collection + document (role-gated server-side).
     await dataStore.createCollection('ledger', { userScope: 'workspace' });
@@ -613,7 +619,8 @@ function Team() {
     );
 
     const mine = await workspaces.list(); // workspaces I belong to
-    const members = await workspaces.listMembers(ws.workspaceId);
+    const members = await workspaces.listMembers(ws.workspaceId); // [{ ref, displayName, role, … }]
+    await workspaces.updateMember(ws.workspaceId, { ref: members[1].ref }, 'admin');
   }
 }
 ```
@@ -628,7 +635,14 @@ if (holder?.type === 'org') {
 }
 ```
 
-**Methods:** `create`, `openForWorkspace`, `list`, `get`, `archive` (owner only — final: an archived workspace cannot be reopened, and it is deleted with its documents 30 days later; say so before your user archives), `listMembers`, `addMember`, `updateMember`, `removeMember`. `addMember(workspaceId, username, role, expiresAt?)` accepts an optional ISO-8601 `expiresAt` to grant **time-bounded** access (e.g. a contractor seat) — owners cannot expire; an expired member is treated as no longer a member. **Rate limits (per minute):** `create`/`archive` 20, member ops 30, `list`/`get`/`listMembers` 120. **Error codes:** `NOT_A_MEMBER`, `FORBIDDEN`, `ROLE_CEILING`, `MUST_KEEP_ONE_OWNER`, `WORKSPACE_NOT_FOUND`, `HOLDER_BACKED_WORKSPACE`, `HOLDER_NOT_ELIGIBLE`. Read workspace documents with `useFiasDataStore().get`/`query`/`search` passing `{ workspaceId }` (every active member can read; make the collection `searchable` to use `search`). **Per-collection role floors:** raise a workspace collection's minimum role at creation — `createCollection('board_minutes', { userScope: 'workspace', writeMinRole: 'admin', readMinRole: 'member' })` makes that collection admin-write / member-read, above the default (write ≥ member, read ≥ viewer).
+**Naming people.** Store `useFiasUser().ref` wherever your data names a person (an assignee, an "uploaded by"), and turn refs back into names with `resolvePeople(refs, workspaceId)`: up to 100 at a time, in order, each `{ ref, displayName, avatar }` or `null`. A ref is named only while it belongs to a current member of that workspace — someone who left, an unknown ref or another app's ref is `null`, and you can't tell which. Without `workspaceId` only the user's own ref resolves. In a Fias org workspace, names also need the `data:workspace-people:read` permission (human-reviewed) **and** the workspace's approval of your app covering it; without both every ref is `null`, so show a neutral label. Names never come with an id or an email.
+
+```tsx
+const [assignee] = await workspaces.resolvePeople([task.assigneeRef], shared.workspaceId);
+const label = assignee?.displayName ?? 'Former member';
+```
+
+**Methods:** `create`, `openForWorkspace`, `list`, `get`, `archive` (owner only — final: an archived workspace cannot be reopened, and it is deleted with its documents 30 days later; say so before your user archives), `listMembers`, `addPeople`, `updateMember`, `removeMember`, `resolvePeople`. **Add people with `addPeople(workspaceId, { role? })`**: Fias draws a sheet in which the person picks co-members of their Fias workspace or types an exact username, and may change the role (you suggest `'admin'`, `'member'` or `'viewer'`); it resolves with `{ added: [{ ref, displayName, role }] }` — empty if they added no one. Your code never names who to add. (`addMember(workspaceId, username, …)` is deprecated: it works only for apps from before app user refs, and in the dev harness and Forge test channel; elsewhere it rejects with `ADD_MEMBER_USE_SHEET`.) Members come back named by your app's `ref` for them and their `displayName` — never a username or id — and `updateMember` / `removeMember` take that `{ ref }`. **Rate limits (per minute):** `create`/`archive` 20, member ops 30, `list`/`get`/`listMembers`/`resolvePeople` 120. **Error codes:** `NOT_A_MEMBER`, `FORBIDDEN`, `ROLE_CEILING`, `ADD_PEOPLE_UNAVAILABLE` (no sheet here: the Forge test channel, Company portals), `MEMBER_TARGET_USE_REF` (name members by `{ ref }`), `SHEET_BUSY`, `MUST_KEEP_ONE_OWNER`, `WORKSPACE_NOT_FOUND`, `HOLDER_BACKED_WORKSPACE`, `HOLDER_NOT_ELIGIBLE`. Read workspace documents with `useFiasDataStore().get`/`query`/`search` passing `{ workspaceId }` (every active member can read; make the collection `searchable` to use `search`). **Per-collection role floors:** raise a workspace collection's minimum role at creation — `createCollection('board_minutes', { userScope: 'workspace', writeMinRole: 'admin', readMinRole: 'member' })` makes that collection admin-write / member-read, above the default (write ≥ member, read ≥ viewer).
 
 ### `useFiasAccess()` — The current user's own access in a workspace
 
@@ -1785,6 +1799,45 @@ await connections.release(connectionId); // give up your own access (owners and
 
 A person connects an outside account (X: `'x'`, LinkedIn: `'linkedin'`) to a Fias workspace — their personal one, or an organization's, where only owners and admins can — and lets your app use it. Your app **never sees a credential**: `connect(provider)` opens a screen the platform draws (it offers the workspace's existing accounts for that provider, or connects a new one in a popup) and resolves with the connection the person chose, or `{ canceled: true }`. `list()` returns only the accounts the workspace the app is open in lets it use; one with `status: 'needs_reconnect'` needs the person to connect it again. People manage connections and every app's access in Workspace Controls. `release` gives up the app's access for the whole workspace, so only the workspace's owners and admins may call it (`ROLE_NOT_ALLOWED` otherwise). Not available in the builder preview or the test channel. **Error codes:** `CONNECTION_NOT_FOUND`, `PERMISSION_DENIED`, `CONNECT_UNAVAILABLE`, `ROLE_NOT_ALLOWED`.
 
+### `useFiasWebSources()` — Read pages on Fias-approved websites, as data
+
+**Permission:** `web:sources:read` (human-reviewed at publish)
+**Returns:** `FiasWebSourcesApi`
+
+```tsx
+import { useFiasWebSources } from '@fias/arche-sdk';
+
+const web = useFiasWebSources();
+const { sites } = await web.listSites({ category: 'credit_union', search: 'becu' });
+// [{ host: 'www.becu.org', name: 'BECU', category: 'credit_union' }]
+const result = await web.extract({
+  url: 'https://www.becu.org/everyday-banking/certificates',
+  form: {
+    description: 'Share certificate rates',
+    fields: {
+      asOf: { kind: 'date', description: 'Date the rates are effective, if stated' },
+      rates: {
+        kind: 'list',
+        maxItems: 50,
+        item: {
+          product: { kind: 'enum', values: ['certificate', 'ira_certificate', 'other'] },
+          months: { kind: 'integer', min: 1, max: 120, description: 'Term in months' },
+          apy: { kind: 'number', min: 0, max: 25, description: 'APY in percent' },
+        },
+      },
+    },
+  },
+  maxAgeSeconds: 24 * 3600,
+});
+// result.data.rates, result.site.name, result.fetchedAt, result.fromCache, result.discarded
+```
+
+Your app reads pages only on **websites Fias approved** (regulated institutions such as credit unions and banks, and government sites) — any page on an approved site, so a redesigned or moved page keeps working. To have a site approved, ask Fias. `listSites()` lists them (free).
+
+`extract()` never returns the page's text — not even a short label. You send a **form** — up to 30 fields of kinds `number` and `integer` (optional `min`/`max`), `boolean`, `date` (`YYYY-MM-DD`), `enum` (your own `values`) and `list` (up to 200 rows of those) — and Fias reads the page into it. There is no free-text kind: describe what you need as numbers, dates, yes/no and choices you list (a product type, not a product name). Every value may be `null` (the page did not say); a value that broke its field's rules comes back `null` and is named in `discarded`. URLs must be `https://`; `redirected: true` means the site moved the page within itself (the new address is not returned). The reader fills the form from whatever layout the page has, but it never runs JavaScript: a page that builds its figures with scripts comes back with `scriptHeavy: true` and mostly nulls — read the site's PDF rate sheet instead.
+
+One copy of each page serves every app, and a page is fetched from its site **at most once an hour**. `maxAgeSeconds` (default one day, 3600–30 days) is the oldest copy you accept. A fresh fetch (about a tenth of a cent) and the reading (a fast model's tokens — well under a cent for a typical page) are charged to the user; a cached result costs nothing (`fromCache: true`). `stale: true` means the site could not be asked again just now and you got the last copy. Always show `site.name` and `fetchedAt` beside the figures. Not available in the builder preview or the test channel. **Error codes:** `WEB_SOURCES_DISABLED`, `INVALID_URL`, `SITE_NOT_APPROVED`, `PAGE_EXCLUDED` (a part of the site where the public posts), `ROBOTS_DISALLOWED`, `FETCH_FAILED`, `RESPONSE_TOO_LARGE`, `CONTENT_TYPE_NOT_ALLOWED`, `EXTRACTION_FAILED`, `SOURCE_BUSY`, `RATE_LIMIT` (surface it, never retry in a loop), `INSUFFICIENT_CREDITS`, `PERMISSION_DENIED`.
+
 ### `useFiasX()` / `useFiasLinkedIn()` — Act as a connected account
 
 **Permission:** `connections:use` (human-reviewed at publish)
@@ -1844,7 +1897,7 @@ 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 })),
+  to: assigneeRefs.map((ref) => ({ ref })), // refs your app stored (useFiasUser().ref)
   subject: 'Your weekly digest',
   text: digestText, // required
   html: digestHtml, // optional, sanitized
@@ -1853,7 +1906,7 @@ const { results, sent } = await email.send({
 ```
 
 - **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).
+- **Name members by their ref** (`{ ref }` — see Naming people under `useFiasWorkspaces()`); you never see their addresses. A ref that names no one is refused exactly like a member outside what the Company allowed. `{ userId }` is deprecated and accepted only from apps that existed before refs. 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`).
@@ -2319,7 +2372,7 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 
 Other optional sub-fields: `currency: "usd"` (only USD supported today), `platformFeePercent` (override the default platform cut — non-standard).
 
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `storage:local`, `data:store`, `data:search`, `data:workspace`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `vault:user-documents:read`, `vault:user-documents:write`, `vault:user-documents:edit`, `vault:workspace-documents:read`, `vault:creative:read`, `vault:creative:write`, `opener:send`, `assets:read`, `assets:community:read`, `assets:community:publish`, `litcraft:hub`, `navigation:open_arche`, `sandbox:vendored-libraries`, `ai:actions`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `storage:local`, `data:store`, `data:search`, `data:workspace`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `vault:user-documents:read`, `vault:user-documents:write`, `vault:user-documents:edit`, `vault:workspace-documents:read`, `vault:creative:read`, `vault:creative:write`, `opener:send`, `assets:read`, `assets:community:read`, `assets:community:publish`, `litcraft:hub`, `navigation:open_arche`, `sandbox:vendored-libraries`, `ai:actions`, `connections:use`, `schedule:invoke`, `web:sources:read`
 
 **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID (or a `{ capability }` selector, or an entry from `useTextModels()`) and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.