(core) flesh out getAccessToken API documentation

Summary:
This extends the getAccessToken documentation so it can be picked
up by typedoc and published, and makes a few other tweaks along
the way prompted by a typescript/typedoc version change.

Test Plan: made in concert with a grist-help update

Reviewers: jarek

Reviewed By: jarek

Subscribers: jarek

Differential Revision: https://phab.getgrist.com/D3548

app/plugin/DocApiTypes.ts

@@ -4,7 +4,11 @@ import { CellValue } from "app/plugin/GristData";
  * JSON schema for api /record endpoint. Used in POST method for adding new records.
  */
 export interface NewRecord {
-  fields?: { [coldId: string]: CellValue }; // fields is optional, user can create blank records
+  /**
+   * Initial values of cells in record. Optional, if not set cells are left
+   * blank.
+   */
+  fields?: { [coldId: string]: CellValue };
 }
 
 /**
@@ -19,7 +23,16 @@ export interface Record {
  * JSON schema for api /record endpoint. Used in PUT method for adding or updating records.
  */
 export interface AddOrUpdateRecord {
+  /**
+   * The values we expect to have in particular columns, either by matching with
+   * an existing record, or creating a new record.
+   */
   require: { [coldId: string]: CellValue } & { id?: number };
+
+  /**
+   * The values we will place in particular columns, either overwriting values in
+   * an existing record, or setting initial values in a new record.
+   */
   fields?: { [coldId: string]: CellValue };
 }
 
@@ -46,6 +59,9 @@ export interface RecordsPut {
 
 export type RecordId = number;
 
+/**
+ * The row id of a record, without any of its content.
+ */
 export interface MinimalRecord {
   id: number
 }

app/plugin/GristAPI.ts

@@ -133,12 +133,40 @@ export interface GristView {
   setSelectedRows(rowIds: number[]): Promise<void>;
 }
 
+/**
+ * Options when creating access tokens.
+ */
 export interface AccessTokenOptions {
-  readOnly?: boolean;   // restrict use of token to reading.
+  /** Restrict use of token to reading only */
+  readOnly?: boolean;
 }
 
+/**
+ * Access token information, including the token string itself, a base URL for
+ * API calls for which the access token can be used, and the time-to-live the
+ * token was created with.
+ */
 export interface AccessTokenResult {
-  token: string;        // token string
-  baseUrl: string;      // url of document api, like https://..../api/docs/DOCID
-  ttlMsecs: number;     // number of milliseconds token will be valid for (typically several minutes)
+  /**
+   * The token string, which can currently be provided in an api call as a
+   * query parameter called "auth"
+   */
+  token: string;
+
+  /**
+   * The base url of the API for which the token can be used. Currently tokens
+   * are associated with a single document, so the base url will be something
+   * like `https://..../api/docs/DOCID`
+   *
+   * Access tokens currently only grant access to endpoints dealing with the
+   * internal content of a document (such as tables and cells) and not its
+   * metadata (such as the document name or who it is shared with).
+   */
+  baseUrl: string;
+
+  /**
+   * Number of milliseconds the access token will remain valid for
+   * after creation. This will be several minutes.
+   */
+  ttlMsecs: number;
 }

app/plugin/GristData.ts

@@ -1,4 +1,6 @@
-// Letter codes for CellValue types encoded as [code, args...] tuples.
+/**
+ * Letter codes for CellValue types encoded as [code, args...] tuples.
+ */
 export enum GristObjCode {
   List            = 'L',
   LookUp          = 'l',
@@ -15,6 +17,9 @@ export enum GristObjCode {
   Versions        = 'V',
 }
 
+/**
+ * Possible types of cell content.
+ */
 export type CellValue = number|string|boolean|null|[GristObjCode, ...unknown[]];
 export interface BulkColValues { [colId: string]: CellValue[]; }
 

app/plugin/grist-plugin-api.ts

@@ -161,7 +161,21 @@ export function getTable(tableId?: string): TableOperations {
 
 /**
  * Get an access token, for making API calls outside of the custom widget
- * API. There is no caching of tokens.
+ * API. There is no caching of tokens. The returned token can
+ * be used to authorize regular REST API calls that access the content of the
+ * document. For example, in a custom widget for a table with a `Photos` column
+ * containing attachments, the following code will update the `src` of an
+ * image with id `the_image` to show the attachment:
+ * ```js
+ * grist.onRecord(async (record) => {
+ *   const tokenInfo = await grist.docApi.getAccessToken({readOnly: true});
+ *   const img = document.getElementById('the_image');
+ *   const id = record.Photos[0];  // get an id of an attachment - there could be several
+ *                                 // in a cell, for this example we just take the first.
+ *   const src = `${tokenInfo.baseUrl}/attachments/${id}/download?auth=${tokenInfo.token}`;
+ *   img.setAttribute('src', src);
+ * });
+ * ```
  */
 export async function getAccessToken(options?: AccessTokenOptions): Promise<AccessTokenResult> {
   return docApi.getAccessToken(options || {});