diff --git a/app/plugin/DocApiTypes.ts b/app/plugin/DocApiTypes.ts index 5a1a60a7..97e832b5 100644 --- a/app/plugin/DocApiTypes.ts +++ b/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 } diff --git a/app/plugin/GristAPI.ts b/app/plugin/GristAPI.ts index 0b4c0d96..c4647d6c 100644 --- a/app/plugin/GristAPI.ts +++ b/app/plugin/GristAPI.ts @@ -133,12 +133,40 @@ export interface GristView { setSelectedRows(rowIds: number[]): Promise; } +/** + * 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; } diff --git a/app/plugin/GristData.ts b/app/plugin/GristData.ts index 610a694e..6853cdd2 100644 --- a/app/plugin/GristData.ts +++ b/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[]; } diff --git a/app/plugin/grist-plugin-api.ts b/app/plugin/grist-plugin-api.ts index 01b81d7a..375c232f 100644 --- a/app/plugin/grist-plugin-api.ts +++ b/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 { return docApi.getAccessToken(options || {});