@fias/arche-sdk 2.30.0 → 2.32.0

package/dist/types.d.ts

@@ -13,9 +13,20 @@ export { VALID_PLUGIN_PERMISSIONS, isValidPluginPermission } from './generated/p
  * User profile data available via useFiasUser() hook.
  */
 export interface FiasUser {
-    userId: string;
+    /**
+     * Your app's identifier for this person (`aur_…`). The same everywhere in
+     * your app, different in every other app, so it can't link people across
+     * apps. Store it wherever your data names a person.
+     */
+    ref: string;
     displayName: string;
     avatar: string | null;
+    /**
+     * @deprecated The platform user id. Present only for apps that existed
+     * before app user refs, until the sunset; new apps never receive it. Use
+     * `ref`. Removed in the next major version.
+     */
+    userId?: string;
 }
 /**
  * Platform theme tokens available via useFiasTheme() hook.
@@ -596,7 +607,7 @@ export interface ImageGenerationParams {
      */
     referenceStrength?: number;
     /**
-     * Generate in a style from the user's Creative Library (ADR-035) — a style
+     * Generate in a style from the user's Creative Library (ADR-037) — a style
      * made in FiasWorks Studio, say. Needs `vault:creative:read`. The platform
      * adds the style's reference pictures after your own references (up to
      * three, while the model has room) and its words to the prompt; with no
@@ -609,7 +620,7 @@ export interface ImageGenerationParams {
      *
      * Or `{ shipped: key }`: a style this arche ships for its players — listed
      * in the manifest's `styles` with its pictures in the asset library tagged
-     * `style:<key>` (ADR-035 D7). No permission beyond this one. It is read
+     * `style:<key>` (ADR-037 D7). No permission beyond this one. It is read
      * from the arche's PUBLISHED version — publish once with the style before
      * relying on it; the dev harness has none (SHIPPED_STYLE_UNAVAILABLE). The
      * player pays, as for any generation.
@@ -865,6 +876,20 @@ export interface FiasChromeState {
      * plugin that owns its chrome draws its own (`setSidebarCollapsed(false)`).
      */
     hostExpandButton: boolean;
+    /**
+     * Where the person came from, when a Fias tool opened this arche — the forge
+     * page's "Open FiasWorks Studio", say (ADR-037 D8) — or null. `useOpener`
+     * reads it without taking the chrome over. A host older than this field
+     * sends none (read it as null).
+     */
+    opener?: FiasOpener | null;
+}
+/** A Fias tool this arche was opened from (ADR-037 D8). */
+export interface FiasOpener {
+    /** What it is: a Fias Forge, or an arche in the Arche Builder. */
+    kind: 'forge' | 'builder';
+    /** The arche's name as the person knows it ("My Arche"). */
+    name: string;
 }
 /** What `chrome_set` may carry — every present key a boolean. */
 export interface FiasChromeSetPayload {
@@ -874,7 +899,7 @@ export interface FiasChromeSetPayload {
     hostExpandButton?: boolean;
 }
 /** The host destinations a plugin may leave for — a closed enum, never a URL. */
-export type FiasChromeNavigateTarget = 'home' | 'worktop';
+export type FiasChromeNavigateTarget = 'home' | 'worktop' | 'opener';
 /**
  * Host-chrome API available via useFiasChrome() — the state above plus the
  * controls the platform's own focus-mode bar carries, so a plugin can place
@@ -1893,8 +1918,10 @@ export interface CommunityAssetUrl {
 }
 export interface CommunityAssetPublishInput {
     /**
-     * The `fileId` from a `useImageGeneration()` result — the image must be one
-     * YOU created or uploaded, in your own Fias files.
+     * The `fileId` of an image the user made IN THIS APP: a `useImageGeneration()`
+     * result, or a picture uploaded through `useVaultDocuments().upload()`. A
+     * file in the user's Documents (even one they granted you) is not
+     * publishable by id — save your own copy with `upload()` first.
      *
      * Required here, while `ImageGenerationResult.fileId` is OPTIONAL (it is
      * absent if the generated image was never written to the user's files). That
@@ -1922,7 +1949,8 @@ export interface CommunityAssetPublishInput {
  * One item's outcome from `publishMany`. Items succeed or fail INDEPENDENTLY —
  * a single rejected page must not sink a whole book — and retrying only the
  * failures is safe: publishing the same bytes twice returns the first result
- * rather than creating a duplicate.
+ * rather than creating a duplicate. An item the user can't pay the safety check
+ * for fails with `INSUFFICIENT_CREDITS`; the ones before it still went through.
  */
 export type CommunityAssetPublishResult = {
     clientRef: string | null;
@@ -1953,8 +1981,14 @@ export type CommunityAssetReportReason = 'sexual' | 'violence' | 'hate' | 'illeg
 export interface CommunityAssetsApi {
     /**
      * Publish one image you created so other users of this arche can see it.
-     * Free. It becomes visible only after moderation — expect
+     * It becomes visible only after moderation — expect
      * `status: 'pending_moderation'` back, not `'published'`.
+     *
+     * The user pays for each picture's safety check (0.6 credits, charged when it
+     * runs; publishing the same bytes again costs nothing). A user who can't pay
+     * for it — and for their pictures still waiting to be checked — is refused
+     * with `INSUFFICIENT_CREDITS` before anything is stored; tell them, rather
+     * than retrying.
      */
     publish: (input: CommunityAssetPublishInput) => Promise<CommunityAsset>;
     /** Publish up to 20 at once; each item succeeds or fails on its own. */
@@ -1983,11 +2017,17 @@ export interface CommunityAssetsApi {
     }>;
 }
 /**
- * A recipient: a member named by user id (the address is resolved by the
- * platform and never returned to the app), or a raw address — accepted only
- * when the Company allowed this app to email anyone.
+ * A recipient: a member named by your app's ref for them (`FiasUser.ref`, or a
+ * ref you stored — the address is resolved by the platform and never returned
+ * to the app), or a raw address — accepted only when the Company allowed this
+ * app to email anyone. `{ userId }` is deprecated and accepted only from apps
+ * that existed before refs.
  */
 export type CompanyEmailRecipient = {
+    ref: string;
+}
+/** @deprecated Use `{ ref }`. Accepted only from apps that existed before refs. */
+ | {
     userId: string;
 } | {
     email: string;
@@ -2077,6 +2117,127 @@ export interface FiasConnectionsApi {
     /** Give up this app's access to one connection. */
     release: (connectionId: string) => Promise<void>;
 }
+export type FiasWebSourceSiteCategory = 'credit_union' | 'bank' | 'government' | 'other';
+/** A website Fias approved for apps to read. Any page on it (or its `www.` twin) may be read. */
+export interface FiasWebSourceSite {
+    host: string;
+    name: string;
+    category: FiasWebSourceSiteCategory;
+}
+export interface FiasWebSourceListOptions {
+    category?: FiasWebSourceSiteCategory;
+    /** Matched against the site's name and host. */
+    search?: string;
+    /** 1–200; default 50. */
+    limit?: number;
+    offset?: number;
+}
+export interface FiasWebSourceSiteList {
+    sites: FiasWebSourceSite[];
+    total: number;
+    /** Pass as `offset` for the next page; null on the last page. */
+    nextOffset: number | null;
+}
+/**
+ * One field of a form. Every value may come back `null` (the page did not
+ * say). Fias enforces the kinds in code: a value that breaks its field's rules
+ * is returned as `null` and named in `discarded`. There is no free-text kind —
+ * a page never gets words of its own in front of your app; describe what you
+ * need as numbers, dates, yes/no and your own `enum` choices.
+ */
+export type FiasWebSourceFormScalarField = {
+    kind: 'number';
+    description?: string;
+    min?: number;
+    max?: number;
+} | {
+    kind: 'integer';
+    description?: string;
+    min?: number;
+    max?: number;
+} | {
+    kind: 'boolean';
+    description?: string;
+}
+/** `YYYY-MM-DD`. */
+ | {
+    kind: 'date';
+    description?: string;
+}
+/** One of `values` (1–50 values, each ≤ 60 characters). */
+ | {
+    kind: 'enum';
+    description?: string;
+    values: string[];
+};
+/** Rows of a table: up to `maxItems` (≤ 200) objects of scalar fields. */
+export interface FiasWebSourceFormListField {
+    kind: 'list';
+    description?: string;
+    maxItems?: number;
+    item: Record<string, FiasWebSourceFormScalarField>;
+}
+export type FiasWebSourceFormField = FiasWebSourceFormScalarField | FiasWebSourceFormListField;
+/**
+ * What to read off the page: up to 30 fields, names matching
+ * `^[a-zA-Z][a-zA-Z0-9_]{0,39}$`. Descriptions (≤ 200 characters) tell the
+ * reader what each field means.
+ */
+export interface FiasWebSourceForm {
+    /** What the form is for (≤ 300 characters). */
+    description?: string;
+    fields: Record<string, FiasWebSourceFormField>;
+}
+export type FiasWebSourceValue = number | boolean | string | null;
+export type FiasWebSourceData = Record<string, FiasWebSourceValue | Array<Record<string, FiasWebSourceValue>>>;
+export interface FiasWebSourceExtractRequest {
+    /** An `https://` page on an approved site. */
+    url: string;
+    form: FiasWebSourceForm;
+    /**
+     * The oldest copy you will accept, in seconds (default one day, up to 30
+     * days). A page is fetched from its site at most once an hour for the
+     * whole platform, so anything under 3600 is treated as 3600.
+     */
+    maxAgeSeconds?: number;
+}
+export interface FiasWebSourceExtraction<T extends FiasWebSourceData = FiasWebSourceData> {
+    url: string;
+    /**
+     * The site redirected this address to another page on the same site, and
+     * that page is what was read. The new address is not returned: it is text
+     * the site chose.
+     */
+    redirected: boolean;
+    site: FiasWebSourceSite;
+    /** When the page was fetched from its site (ISO 8601) — show it beside the figures. */
+    fetchedAt: string;
+    /** Older than `maxAgeSeconds`: the site could not be asked again just now. */
+    stale: boolean;
+    /** Nothing was fetched or read for this call, so nothing was charged. */
+    fromCache: boolean;
+    /** The page's values, in the form's shape. */
+    data: T;
+    /** Fields (and list rows) whose values broke the form's rules and became null or were dropped. */
+    discarded: string[];
+    /** The page was longer than the reader reads; values past the cut are missing. */
+    pageTruncated: boolean;
+    /**
+     * Scripts present and almost no text: the page probably builds its content
+     * with JavaScript, which is never run. Read the site's PDF or data address instead.
+     */
+    scriptHeavy: boolean;
+}
+export interface FiasWebSourcesApi {
+    /** The sites Fias approved for apps to read. Free. */
+    listSites: (options?: FiasWebSourceListOptions) => Promise<FiasWebSourceSiteList>;
+    /**
+     * A page on an approved site, read into `form`. A fresh fetch (about a
+     * tenth of a cent) and the reading (a fast model's tokens) are charged to
+     * the user; a cached result is free. Never returns the page's text.
+     */
+    extract: <T extends FiasWebSourceData = FiasWebSourceData>(request: FiasWebSourceExtractRequest) => Promise<FiasWebSourceExtraction<T>>;
+}
 export type FiasCreativeItemKind = 'style' | 'character';
 /** A style or character, as the Creative Library returns it. */
 export interface FiasCreativeItem {
@@ -2126,7 +2287,7 @@ export interface FiasCreativeLibraryApi {
     }) => Promise<FiasCreativeItem[]>;
     /** One item, with preview URLs; pass `version` for an earlier version. */
     get: (itemId: string, version?: number) => Promise<FiasCreativeItem>;
-    /** Needs `vault:creative:write`. A style has 1–12 pictures; a character exactly one. */
+    /** Needs `vault:creative:write`. A style has 1–100 pictures; a character exactly one. */
     create: (fields: FiasCreativeItemFields & {
         kind: FiasCreativeItemKind;
         name: string;
@@ -2153,6 +2314,36 @@ export interface FiasCreativeLibraryApi {
         kind?: FiasCreativeItemKind;
     }) => Promise<FiasCreativePickResult>;
 }
+/**
+ * Where the person came from, and what you can do about it (ADR-037 D8) —
+ * `useOpener()`.
+ */
+export interface FiasOpenerApi {
+    /** The Fias tool that opened this arche, or null — then show neither action. */
+    opener: FiasOpener | null;
+    /** Take the person back to `opener`. Does nothing without one. */
+    returnTo: () => void;
+    /**
+     * Offer one of YOUR files (a Vault file this arche created) to `opener`:
+     * Fias shows the person a sheet naming the file and the destination, and
+     * their Send moves it — into a Fias Forge's `public/`, or an Arche Builder
+     * arche's asset library. `name` is the name it should land as. Requires
+     * `opener:send`. Resolves `{ sent: true, name }` once it arrived (the name
+     * it landed as), or `{ canceled: true }`. Rejects with `NO_OPENER` without
+     * an `opener`, `SHEET_BUSY` while another Fias sheet is open, and
+     * `SEND_UNAVAILABLE` where there is none (the dev harness).
+     */
+    send: (file: {
+        fileId: string;
+        name?: string;
+    }) => Promise<FiasSendToOpenerResult>;
+}
+export type FiasSendToOpenerResult = {
+    sent: true;
+    name: string;
+} | {
+    canceled: true;
+};
 /** What `useCreativeLibrary().pick()` resolves with. */
 export type FiasCreativePickResult = {
     item: {
@@ -2741,6 +2932,13 @@ export interface DataStoreCollectionConstraints {
     immutableFields?: string[];
     references?: DataStoreReference[];
     ledgerSums?: DataStoreLedgerSum[];
+    /**
+     * Field paths that name people (ADR-040): when present, each holds one app
+     * user ref (`useFiasUser().ref`) or an array of up to 20, and nothing else.
+     * Declare every field your data uses for a person — it is what lets Fias
+     * relate your records to people and carry refs safely between apps.
+     */
+    personFields?: string[];
 }
 /**
  * Counter-follows-ledger: `field` on this collection's documents may only
@@ -3155,15 +3353,31 @@ export interface DataStoreWorkspace {
      */
     holderBacked?: boolean;
 }
-/** A member of a workspace. Members are addressed by username — the platform
- *  userId is internal and never exposed to plugins or users. */
+/**
+ * A member of a workspace (ADR-040 §4). Members are named by your app's `ref`
+ * for them, with their display name; the platform userId is never exposed.
+ * Apps that existed before refs still get `username` instead.
+ */
 export interface DataStoreWorkspaceMember {
-    username: string;
+    /** Your app's ref for this member — pass it back to `updateMember` / `removeMember`. */
+    ref?: string;
+    displayName?: string;
+    /** @deprecated Only for apps that existed before refs, which get it instead of `ref`. */
+    username?: string;
     role: WorkspaceRole;
     grantedAt: string;
     /** ISO-8601 expiry, or null for a permanent membership. Owners never expire. */
     expiresAt: string | null;
 }
+/**
+ * Who a membership change is about: `{ ref }` from `listMembers`. A plain
+ * username string works only for apps from before app user refs (until the
+ * sunset) and in the dev harness and Forge test channel; elsewhere it rejects
+ * with `MEMBER_TARGET_USE_REF`.
+ */
+export type WorkspaceMemberTarget = string | {
+    ref: string;
+};
 /**
  * Workspace tenancy API available via the `useFiasWorkspaces()` hook.
  *
@@ -3207,14 +3421,57 @@ export interface FiasWorkspacesApi {
     archive: (workspaceId: string) => Promise<void>;
     /** List a workspace's members (any member). */
     listMembers: (workspaceId: string) => Promise<DataStoreWorkspaceMember[]>;
-    /** Add a member by username, with a role (owner/admin; cannot grant above your
-     *  own role). Optionally time-bound the membership with an ISO-8601 `expiresAt`
-     *  (owners cannot expire). Rejects with `USER_NOT_FOUND` if no such user. */
+    /**
+     * Let the person add people to a workspace, in a sheet Fias draws (ADR-040).
+     * The person picks co-members of their Fias workspace or types an exact
+     * username, and may change the suggested `role`; you never name anyone.
+     * Resolves with who was added (empty if they added no one), by `ref`.
+     * Rejects with `ADD_PEOPLE_UNAVAILABLE` where Fias draws no sheet (the
+     * Forge test channel) and `SHEET_BUSY` while another sheet is open.
+     */
+    addPeople: (workspaceId: string, options?: {
+        role?: 'admin' | 'member' | 'viewer';
+    }) => Promise<{
+        added: AddedWorkspacePerson[];
+    }>;
+    /**
+     * @deprecated Use `addPeople`. Adding by a username your code supplies works
+     * only for apps that existed before app user refs (until the sunset), and in
+     * the dev harness and Forge test channel; elsewhere it rejects with
+     * `ADD_MEMBER_USE_SHEET`. Owner/admin; cannot grant above your own role;
+     * optional ISO-8601 `expiresAt` (owners cannot expire).
+     */
     addMember: (workspaceId: string, username: string, role: WorkspaceRole, expiresAt?: string) => Promise<DataStoreWorkspaceMember>;
-    /** Change a member's role by username (owner/admin; keeps the one-owner invariant). */
-    updateMember: (workspaceId: string, username: string, role: WorkspaceRole) => Promise<DataStoreWorkspaceMember>;
-    /** Remove a member by username (owner/admin, or yourself; keeps the one-owner invariant). */
-    removeMember: (workspaceId: string, username: string) => Promise<void>;
+    /** Change a member's role (owner/admin; keeps the one-owner invariant). */
+    updateMember: (workspaceId: string, member: WorkspaceMemberTarget, role: WorkspaceRole) => Promise<DataStoreWorkspaceMember>;
+    /** Remove a member (owner/admin, or yourself; keeps the one-owner invariant). */
+    removeMember: (workspaceId: string, member: WorkspaceMemberTarget) => Promise<void>;
+    /**
+     * Names for people your app knows by ref (`FiasUser.ref`, or refs you
+     * stored), any number (an empty list answers `[]`; the SDK pages large
+     * lists), in the order given. A ref is named only
+     * when it belongs to a current member of `workspaceId` — a workspace you
+     * belong to — and every other ref is `null`: someone who left, an unknown
+     * ref, another app's ref. Without `workspaceId`, only the user's own ref
+     * resolves. In a Fias org workspace, names also need `data:workspace-people:read`
+     * and the workspace's approval of your app covering it; otherwise every ref
+     * is `null`. Never returns an id or an email. Refuses like `get` when you
+     * are not a member.
+     */
+    resolvePeople: (refs: string[], workspaceId?: string) => Promise<(FiasPerson | null)[]>;
+}
+/** Someone the person added in the Add people sheet (ADR-040). */
+export interface AddedWorkspacePerson {
+    /** Your app's ref for them. */
+    ref: string;
+    displayName: string;
+    role: string;
+}
+/** A person your app named by ref (ADR-040): display name only, never an id. */
+export interface FiasPerson {
+    ref: string;
+    displayName: string;
+    avatar: string | null;
 }
 /**
  * The current user's access in one workspace where only workspace TIERS