@fias/arche-sdk 2.31.0 → 2.33.0

package/dist/theme.js

@@ -15,6 +15,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LIGHT_THEME = exports.DARK_THEME = void 0;
 exports.getDefaultTheme = getDefaultTheme;
+exports.normalizeFiasBrand = normalizeFiasBrand;
 const SYSTEM_FONTS = '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
 const MONO_FONTS = '"SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace';
 const SHARED_SPACING = { xs: '4px', sm: '8px', md: '16px', lg: '24px', xl: '32px' };
@@ -82,4 +83,37 @@ exports.LIGHT_THEME = {
 function getDefaultTheme(mode) {
     return mode === 'light' ? exports.LIGHT_THEME : exports.DARK_THEME;
 }
+const BRAND_HEX = /^#[0-9a-fA-F]{6}$/;
+/** Well above the platform's stored-logo cap (64 KB data URL); refuses a value nobody should draw. */
+const BRAND_LOGO_URL_MAX = 256 * 1024;
+const BRAND_NAME_MAX = 200;
+/**
+ * A Company brand in the shape apps receive it (`FiasTheme.brand`), or
+ * `undefined` when there is nothing to show. Used by every host — the
+ * platform, the builder preview and the dev harness — and again by the SDK on
+ * what arrives, so an app can rely on the shape whoever sent it: colours are
+ * `#RRGGBB` or null, the logo is a `data:image/` or `https:` URL or null.
+ */
+function normalizeFiasBrand(input) {
+    if (!input || typeof input !== 'object')
+        return undefined;
+    const raw = input;
+    const color = (v) => (typeof v === 'string' && BRAND_HEX.test(v) ? v : null);
+    const name = typeof raw.displayName === 'string' && raw.displayName.trim() !== ''
+        ? raw.displayName.trim().slice(0, BRAND_NAME_MAX)
+        : null;
+    const logo = typeof raw.logoUrl === 'string' &&
+        raw.logoUrl.length <= BRAND_LOGO_URL_MAX &&
+        (raw.logoUrl.startsWith('data:image/') || raw.logoUrl.startsWith('https://'))
+        ? raw.logoUrl
+        : null;
+    const brand = {
+        displayName: name,
+        logoUrl: logo,
+        primaryColor: color(raw.primaryColor),
+        accentColor: color(raw.accentColor),
+        headerTextColor: color(raw.headerTextColor),
+    };
+    return Object.values(brand).some((v) => v !== null) ? brand : undefined;
+}
 //# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -1 +1 @@
-{"version":3,"file":"theme.js","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAwEH,0CAEC;AAtED,MAAM,YAAY,GAAG,mEAAmE,CAAC;AACzF,MAAM,UAAU,GAAG,iEAAiE,CAAC;AAErF,MAAM,cAAc,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;AACpF,MAAM,YAAY,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AACrF,MAAM,iBAAiB,GAA4B;IACjD,YAAY,EAAE,QAAQ;IACtB,YAAY,EAAE,UAAU;IACxB,UAAU,EAAE,QAAQ;IACpB,WAAW,EAAE,UAAU;IACvB,QAAQ,EAAE,iCAAiC;IAC3C,QAAQ,EAAE,sEAAsE;IAChF,QAAQ,EAAE,wEAAwE;IAClF,WAAW,EAAE,KAAK;CACnB,CAAC;AAEW,QAAA,UAAU,GAAc;IACnC,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE;QACN,OAAO,EAAE,SAAS;QAClB,WAAW,EAAE,SAAS;QACtB,SAAS,EAAE,SAAS;QACpB,MAAM,EAAE,SAAS;QACjB,UAAU,EAAE,SAAS;QACrB,OAAO,EAAE,SAAS;QAClB,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,SAAS;QACnB,IAAI,EAAE,SAAS;QACf,aAAa,EAAE,SAAS;QACxB,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,SAAS;QACpB,MAAM,EAAE,SAAS;QACjB,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,SAAS;QAClB,IAAI,EAAE,SAAS;KAChB;IACD,OAAO,EAAE,cAAc;IACvB,KAAK,EAAE,YAAY;IACnB,UAAU,EAAE,iBAAiB;CAC9B,CAAC;AAEW,QAAA,WAAW,GAAc;IACpC,IAAI,EAAE,OAAO;IACb,MAAM,EAAE;QACN,OAAO,EAAE,SAAS;QAClB,WAAW,EAAE,SAAS;QACtB,SAAS,EAAE,SAAS;QACpB,MAAM,EAAE,SAAS;QACjB,UAAU,EAAE,SAAS;QACrB,OAAO,EAAE,SAAS;QAClB,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,SAAS;QACnB,IAAI,EAAE,SAAS;QACf,aAAa,EAAE,SAAS;QACxB,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,SAAS;QACpB,MAAM,EAAE,SAAS;QACjB,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,SAAS;QAClB,IAAI,EAAE,SAAS;KAChB;IACD,OAAO,EAAE,cAAc;IACvB,KAAK,EAAE,YAAY;IACnB,UAAU,EAAE,iBAAiB;CAC9B,CAAC;AAEF,SAAgB,eAAe,CAAC,IAAsB;IACpD,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,mBAAW,CAAC,CAAC,CAAC,kBAAU,CAAC;AACrD,CAAC"}
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"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"}

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.
@@ -63,6 +74,30 @@ export interface FiasTheme {
         shadowLg: string;
         borderWidth: string;
     };
+    /**
+     * The Company's brand (ADR-023), present only while the app runs on that
+     * Company's portal (ADR-024) and the Company has set one. Absent on fias.io
+     * and on a portal without a brand — keep your own palette then. Each field
+     * is null when the Company left it unset.
+     */
+    brand?: FiasBrand;
+}
+/**
+ * A Company's brand as an app receives it in {@link FiasTheme.brand}. The same
+ * tokens the portal's own shell is drawn with, and already public on the
+ * portal: nothing here is about the person using the app.
+ */
+export interface FiasBrand {
+    /** The name the Company shows people, e.g. on its sign-in page. */
+    displayName: string | null;
+    /** The Company's logo, as an image URL (today a `data:` URL) for an `<img src>`. */
+    logoUrl: string | null;
+    /** `#RRGGBB`. The Company's main colour — headers, primary buttons. */
+    primaryColor: string | null;
+    /** `#RRGGBB`. A second colour for highlights and links. */
+    accentColor: string | null;
+    /** `#RRGGBB`. Text drawn on `primaryColor`. */
+    headerTextColor: string | null;
 }
 /**
  * Storage API available via useFiasStorage() hook.
@@ -2006,11 +2041,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;
@@ -2100,6 +2141,157 @@ 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;
+    /**
+     * How many independent readings the page gets (default 1). With `2`, the
+     * page is read twice and only a value both readings agree on is returned;
+     * a field they disagree on comes back `null` and is named in `disagreed`,
+     * so you can put it in front of a person instead of publishing one
+     * reading's guess. Agreement says a value was stable across two readings,
+     * not that it is right. Two readings are two reader charges. Use it
+     * wherever a wrong number matters, such as money. The platform may raise
+     * the floor for every app.
+     */
+    reads?: 1 | 2;
+}
+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: `rates[3].apy`, `rates[50..]`. With two readings a
+     * list is named whole (`rates`): a row index belongs to one reading's rows,
+     * and the agreed list no longer has them in that order.
+     */
+    discarded: string[];
+    /**
+     * Fields the two readings disagreed on: `null` instead of one reading's
+     * value, or for a list only the rows both readings produced. Check it
+     * whatever you asked for: the platform may require two readings of every
+     * app, and a one-reading call is answered from a two-reading result when
+     * one is already stored for the page and form. A list named here may be missing rows the page
+     * prints: never conclude "absent on the page" (not offered, no such term)
+     * from a field in `disagreed`; treat it as unknown and confirm with a
+     * person.
+     */
+    disagreed: 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 each reading (the reader model's tokens; two with
+     * `reads: 2`) are charged to the user; a cached result is free. The reader's
+     * model, and so a reading's price, is chosen by the platform (a fast model
+     * today, well under a cent for a typical page). 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 {
@@ -2794,6 +2986,51 @@ 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[];
+    /**
+     * An attested log (ADR-042): Fias stamps every row with who wrote it — see
+     * {@link DataStoreAttestation} — and no app code, user, agent or
+     * contributor can change a row or delete one on its own. The log ends with
+     * your app: no workspace holding one can be archived (`WORKSPACE_ATTESTED`).
+     * Requires `appendOnly: true` and
+     * the `data:attested` permission; declared only in `fias-plugin.json`, and
+     * only on a NEW collection (never added to one that exists). Not allowed on
+     * `shared` scope.
+     */
+    attested?: true;
+}
+/**
+ * What Fias records beside a row of an attested collection (ADR-042). Never
+ * part of `data`, never writable by your code.
+ *
+ * It proves which person (or agent key acting for them, or Fias AI) wrote the
+ * row, through which channel, when, and under which release of your app. It
+ * does not prove intent or that `data` is true: your code wrote `data`.
+ * Describe it as "platform-attested", never "tamper-evident".
+ */
+export interface DataStoreAttestation {
+    /** The app user ref of the person accountable for the write. Name it with `resolvePeople`. */
+    personRef: string;
+    /** The agent key that wrote it, for `channel: 'agent'` only. Never resolves to a name. */
+    agentRef?: string;
+    /**
+     * How the write arrived: a fias.io session, a Company portal session, Fias
+     * AI, an external agent key, or a dev / test / preview sandbox
+     * (`non_production` — never present such a row as real).
+     */
+    channel: 'session' | 'portal' | 'assistant' | 'agent' | 'non_production';
+    /** When Fias stored the row: the database clock at the insert (ISO 8601). */
+    recordedAt: string;
+    /** Your app's manifest version live when the write was accepted. On every production row; never on a test row. */
+    appVersion?: string;
+    /** The hash of that release's bundle. On every production row; never on a test row. */
+    buildHash?: string;
 }
 /**
  * Counter-follows-ledger: `field` on this collection's documents may only
@@ -2896,6 +3133,8 @@ export interface DataStoreBatchResult {
         key: string;
         version?: number;
         audience?: string;
+        /** The row's attestation, for a row of an attested collection (ADR-042). */
+        attestation?: DataStoreAttestation;
     }[];
 }
 /**
@@ -2914,6 +3153,8 @@ export interface DataStorePutResult {
     key?: string;
     /** The audience the document sits in, in a collection with audiences. */
     audience?: string;
+    /** What Fias recorded about the write, for a row of an attested collection (ADR-042). */
+    attestation?: DataStoreAttestation;
 }
 /**
  * A document returned from the data store.
@@ -2945,6 +3186,8 @@ export interface DataStoreDocument<T = Record<string, unknown>> {
      * audience's readers, never by your code. Absent elsewhere.
      */
     audience?: string;
+    /** Present on rows of an attested collection (ADR-042): see {@link DataStoreAttestation}. */
+    attestation?: DataStoreAttestation;
 }
 /**
  * Filter condition for querying documents.
@@ -3035,6 +3278,8 @@ export interface DataStoreSearchMatch<T = Record<string, unknown>> {
     authoredByCollaborator?: boolean;
     /** The match's audience, in a collection with audiences — see {@link DataStoreDocument.audience}. */
     audience?: string;
+    /** Present on rows of an attested collection — see {@link DataStoreDocument.attestation}. */
+    attestation?: DataStoreAttestation;
 }
 /**
  * Data Store API available via useFiasDataStore() hook.
@@ -3208,15 +3453,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.
  *
@@ -3260,14 +3521,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