@awesomate/sdk 0.26.0 → 0.28.0

package/dist/index.d.ts

@@ -26,7 +26,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export declare const VERSION = "0.26.0";
+export declare const VERSION = "0.28.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -962,9 +962,10 @@ export declare class AwesomateClient {
     }>;
     /**
      * Who this token is: the account, its plan, the token's scopes and when it expires, and which
-     * features the account has (each with the sentence to say when it does not). An account token
-     * acts as the account's owner, whoever made it. Needs hosting:read; an app key cannot ask (it
-     * reads and writes its own kinds only).
+     * features the account has (each with the sentence to say when it does not), and whose key it
+     * is: the account owner's, which acts as the owner, or a team member's own, which does only what
+     * that person can do in the hub. Needs hosting:read; an app key cannot ask (it reads and writes
+     * its own kinds only).
      *
      * @example
      * const me = await db.whoami();
@@ -1842,6 +1843,20 @@ export interface WhoAmI {
         reason: string | null;
         message: string | null;
     }> | null;
+    /**
+     * Whose key this is: `account_owner` (acts as the owner), or `person`, a team member's own key,
+     * which does what that person can do and never more (`level` view or full). Null for a browser
+     * session, or from an older hub.
+     */
+    key: {
+        holder: 'account_owner';
+        email: string | null;
+    } | {
+        holder: 'person';
+        email: string | null;
+        name: string | null;
+        level: 'view' | 'full';
+    } | null;
 }
 /** One column of a kind, from schema(). */
 export interface SchemaColumn {
@@ -2424,6 +2439,45 @@ export interface VoiceSession {
     }>;
     say_as: Record<string, string>;
 }
+/** One field on a record page: its value as this person may read it, and whether they may change it. */
+export interface RecordPageField {
+    key: string;
+    label: string;
+    type: string;
+    value: unknown;
+    change: boolean;
+}
+/** One section on a record page, in the order the account set; `folded` sections start closed. */
+export interface RecordPageSection {
+    key: string;
+    label: string;
+    folded: boolean;
+    fields: RecordPageField[];
+}
+/** A record laid out for the signed-in person's app role (`app.recordPage`). */
+export interface RecordPage {
+    kind: {
+        key: string;
+        label: string;
+        labelPlural: string;
+    };
+    id: string;
+    /** Where it is up to, in the account's words for people outside the team. Null when there are none to show. */
+    stage: {
+        label: string;
+        closed: boolean;
+    } | null;
+    /** Read only from its stage on: nothing on it can be changed. */
+    locked: boolean;
+    /** Whether this person may change the record at all. Each field's `change` says which. */
+    canWrite: boolean;
+    sections: RecordPageSection[];
+    /** Fields the account keeps at the top of the page, in order. */
+    pinned: string[];
+    /** The part of the page it opens on. */
+    tab: 'details' | 'activity' | 'related';
+    asAt: string;
+}
 /**
  * The browser client for one of the account's apps, from createAppClient(): sign-in is under
  * `auth`, and every data call runs as the signed-in person, inside the account's access rules.
@@ -2510,6 +2564,20 @@ export declare class AwesomateAppClient {
      * else names no record, so it answers null without asking the hub. Pro and above.
      */
     get<K extends KindName>(kind: K, id: string): Promise<RowOf<K> | null>;
+    /**
+     * One record laid out for this person: the sections and fields their app role is shown, in the
+     * order the account set for that role, each field with its value and whether they may change it,
+     * and where the record is up to in the account's own words for people outside the team. Null when
+     * there is no such record this person may read. The database decides every permission; the
+     * account sets the layout on the record page in the hub ("Viewing as", the role "in your apps").
+     * Needs the account's record pages. A locked record says `locked: true`, and a change to it fails
+     * with `forbidden` and `serverCode: 'locked'`.
+     *
+     * @example
+     * const page = await app.recordPage('job', job.id);
+     * for (const section of page?.sections ?? []) console.log(section.label, section.fields.map((f) => f.value));
+     */
+    recordPage<K extends KindName>(kind: K, id: string): Promise<RecordPage | null>;
     /** Create a record (returns its id) or change one with options.id, inside the kind's write rule for this user. Pro and above. */
     write<K extends KindName>(kind: K, data: Partial<RowOf<K>> | Record<string, unknown>, options?: WriteOptions): Promise<string>;
     /** Archive a record, inside the kind's write rule for this person. Pro and above. */

package/dist/index.js

@@ -26,7 +26,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export const VERSION = '0.26.0';
+export const VERSION = '0.28.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 /** Every record and contact id is a UUID; anything else can name no row. */
 const RECORD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -709,9 +709,10 @@ export class AwesomateClient {
     }
     /**
      * Who this token is: the account, its plan, the token's scopes and when it expires, and which
-     * features the account has (each with the sentence to say when it does not). An account token
-     * acts as the account's owner, whoever made it. Needs hosting:read; an app key cannot ask (it
-     * reads and writes its own kinds only).
+     * features the account has (each with the sentence to say when it does not), and whose key it
+     * is: the account owner's, which acts as the owner, or a team member's own, which does only what
+     * that person can do in the hub. Needs hosting:read; an app key cannot ask (it reads and writes
+     * its own kinds only).
      *
      * @example
      * const me = await db.whoami();
@@ -725,6 +726,7 @@ export class AwesomateClient {
             scopes: Array.isArray(r.scopes) ? r.scopes.map(String) : [],
             tokenExpiresAt: r.patExpiresAt ?? null,
             features: r.features ?? null,
+            key: r.key ?? null,
         };
     }
     /**
@@ -1320,6 +1322,42 @@ export class AwesomateAppClient {
             throw err;
         }
     }
+    /**
+     * One record laid out for this person: the sections and fields their app role is shown, in the
+     * order the account set for that role, each field with its value and whether they may change it,
+     * and where the record is up to in the account's own words for people outside the team. Null when
+     * there is no such record this person may read. The database decides every permission; the
+     * account sets the layout on the record page in the hub ("Viewing as", the role "in your apps").
+     * Needs the account's record pages. A locked record says `locked: true`, and a change to it fails
+     * with `forbidden` and `serverCode: 'locked'`.
+     *
+     * @example
+     * const page = await app.recordPage('job', job.id);
+     * for (const section of page?.sections ?? []) console.log(section.label, section.fields.map((f) => f.value));
+     */
+    async recordPage(kind, id) {
+        if (!RECORD_ID.test(String(id)))
+            return null;
+        try {
+            const r = await this.data('GET', `/records/${encodeURIComponent(kind)}/${encodeURIComponent(String(id))}`);
+            return {
+                kind: { key: r.kind.key, label: r.kind.label, labelPlural: r.kind.label_plural },
+                id: r.id,
+                stage: r.stage,
+                locked: r.locked,
+                canWrite: r.can_write,
+                sections: r.sections,
+                pinned: r.pinned,
+                tab: r.tab,
+                asAt: r.as_at,
+            };
+        }
+        catch (err) {
+            if (err instanceof AwesomateError && err.code === 'not_found')
+                return null;
+            throw err;
+        }
+    }
     /** Create a record (returns its id) or change one with options.id, inside the kind's write rule for this user. Pro and above. */
     async write(kind, data, options = {}) {
         const r = await this.data('POST', '/call', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Your own Awesomate data from Node and the browser: query contacts and app data with generated types, and sign your app's own users in",
   "license": "MIT",
   "type": "module",